@query-farm/vgi 0.37.1 → 0.38.0

package/src/codec/asd.ts

@@ -40,7 +40,102 @@ export function encodeASD(
   schema: VgiSchema,
   obj: Record<string, any>,
 ): Uint8Array {
-  return serializeBatch(batchFromRows([obj], schema));
+  return serializeBatch(batchFromRows([sortMapsForSchema(schema, obj)], schema));
+}
+
+// --------------------------------------------------------------------------- //
+// Encode side: deterministic map columns
+// --------------------------------------------------------------------------- //
+//
+// A map value arrives as a JS object (or Map / pair list), whose iteration
+// order is insertion order -- except that integer-like keys ("1", "2") always
+// come first, ascending. Two builds of the same record could therefore encode
+// differently (and a catalog_contents content-hash etag would change with no
+// catalog change). Every map is written in sorted key order instead, matching
+// the Go / Java / C# / Rust SDKs: keys compared by Unicode code point (the
+// same order as comparing their UTF-8 bytes), not by UTF-16 code unit.
+
+/** Compare two strings by Unicode code point (= UTF-8 byte order). */
+export function compareCodePoints(a: string, b: string): number {
+  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;
+    // A surrogate (a code point above U+FFFF) sorts after every BMP code unit,
+    // though as a code unit (0xD800-0xDFFF) it sorts below U+E000-U+FFFF.
+    const xs = x >= 0xd800 && x <= 0xdfff;
+    const ys = y >= 0xd800 && y <= 0xdfff;
+    if (xs !== ys) return xs ? 1 : -1;
+    return x - y;
+  }
+  return a.length - b.length;
+}
+
+function mapPairs(raw: any): Array<[unknown, unknown]> {
+  if (Array.isArray(raw)) return raw.map((e: any) => (Array.isArray(e) ? [e[0], e[1]] : [e?.key, e?.value]));
+  if (raw instanceof Map) return Array.from(raw.entries());
+  if (typeof raw[Symbol.iterator] === "function") return Array.from(raw as Iterable<[unknown, unknown]>);
+  return Object.entries(raw);
+}
+
+function compareKeys(a: unknown, b: unknown): number {
+  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));
+}
+
+/** Whether a type contains a map anywhere (memoized per type object). */
+const HAS_MAP = new WeakMap<object, boolean>();
+function typeHasMap(type: VgiDataType): boolean {
+  const cached = HAS_MAP.get(type as object);
+  if (cached !== undefined) return cached;
+  let has = isMap(type);
+  if (!has && (isList(type) || isStruct(type))) {
+    has = ((type as any).children as VgiField[]).some((c) => typeHasMap(c.type));
+  }
+  HAS_MAP.set(type as object, has);
+  return has;
+}
+
+function sortMapsForType(type: VgiDataType, value: any): any {
+  if (value == null || !typeHasMap(type)) return value;
+  if (isMap(type)) {
+    const entries = (type as any).children[0].type as VgiDataType;
+    const valueType = ((entries as any).children as VgiField[])[1].type;
+    return mapPairs(value)
+      .map(([k, v]): [unknown, unknown] => [k, sortMapsForType(valueType, v)])
+      .sort((x, y) => compareKeys(x[0], y[0]));
+  }
+  if (isList(type)) {
+    const child = (type as any).children[0].type as VgiDataType;
+    return Array.from(value as Iterable<unknown>, (v) => sortMapsForType(child, v));
+  }
+  if (isStruct(type)) {
+    const out: Record<string, any> = { ...value };
+    for (const cf of (type as any).children as VgiField[]) out[cf.name] = sortMapsForType(cf.type, value[cf.name]);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * `obj` with every map-typed field (at any depth) as a key-sorted pair list.
+ * Returns `obj` itself when the schema has no map column. Never mutates `obj`
+ * (catalog items may be frozen and shared).
+ */
+export function sortMapsForSchema(schema: VgiSchema, obj: Record<string, any>): Record<string, any> {
+  let out: Record<string, any> | null = 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;
 }
 
 /**

package/src/generated/vgi-client.ts

@@ -2,7 +2,7 @@
 // GENERATED by vgi.codegen.ts_client. DO NOT EDIT BY HAND.
 //
 // Generator: vgi-gen-ts-client v1
-// Content hash: 69731fc31f09
+// Content hash: 5cf87195498c
 //
 // To regenerate:
 //   uv run --project ~/Development/vgi-python vgi-gen-ts-client \
@@ -423,12 +423,33 @@ export interface CatalogAttachResult {
   global_function_prefix: string;
   resolved_data_version?: string | null;
   resolved_implementation_version?: string | null;
+  supports_catalog_contents: boolean;
 }
 
 export interface CatalogsResponse {
   items: CatalogInfo[];
 }
 
+export interface SchemaContents {
+  path: string[];
+  schema: Uint8Array;
+  tables: Uint8Array[];
+  views: Uint8Array[];
+  scalar_functions: Uint8Array[];
+  aggregate_functions: Uint8Array[];
+  table_functions: Uint8Array[];
+  scalar_macros: Uint8Array[];
+  table_macros: Uint8Array[];
+  indexes: Uint8Array[];
+}
+
+export interface CatalogContentsResponse {
+  catalog_version: number;
+  etag?: string | null;
+  not_modified: boolean;
+  schemas: SchemaContents[];
+}
+
 export interface CopyFromFormatsResponse {
   items: Uint8Array[];
 }

package/src/generated/vgi-protocol-schemas.ts

@@ -2,7 +2,7 @@
 // GENERATED by vgi.codegen.ts_schemas. DO NOT EDIT BY HAND.
 //
 // Generator: vgi-gen-ts-schemas v2
-// Content hash: 668f198950df
+// Content hash: 36a9087555c9
 //
 // To regenerate:
 //   uv run --project ~/Development/vgi-python vgi-gen-ts-schemas \
@@ -228,6 +228,20 @@ export const ForeignKeyInfoSchema = schema([
   field("referenced_schema_path", list(field("item", utf8(), true)), false),
 ]);
 
+// Origin: SchemaContents
+export const SchemaContentsSchema = schema([
+  field("path", list(field("item", utf8(), true)), false),
+  field("schema", binary(), false),
+  field("tables", list(field("item", binary(), true)), false),
+  field("views", list(field("item", binary(), true)), false),
+  field("scalar_functions", list(field("item", binary(), true)), false),
+  field("aggregate_functions", list(field("item", binary(), true)), false),
+  field("table_functions", list(field("item", binary(), true)), false),
+  field("scalar_macros", list(field("item", binary(), true)), false),
+  field("table_macros", list(field("item", binary(), true)), false),
+  field("indexes", list(field("item", binary(), true)), false),
+]);
+
 // Origin: AggregateBindRequest
 export const AggregateBindRequestSchema = schema([
   field("function_name", utf8(), false),
@@ -638,6 +652,7 @@ export const CatalogAttachResultSchema = schema([
   field("global_function_prefix", utf8(), false),
   field("resolved_data_version", utf8(), true),
   field("resolved_implementation_version", utf8(), true),
+  field("supports_catalog_contents", bool(), false),
 ]);
 
 // Origin: method 'catalog_catalogs' result
@@ -645,6 +660,14 @@ export const CatalogCatalogsResultSchema = schema([
   field("items", list(field("item", binary(), true)), false),
 ]);
 
+// Origin: method 'catalog_contents' result
+export const CatalogContentsResultSchema = schema([
+  field("catalog_version", int64(), false),
+  field("etag", utf8(), true),
+  field("not_modified", bool(), false),
+  field("schemas", list(field("item", struct([field("path", list(field("item", utf8(), true)), false), field("schema", binary(), false), field("tables", list(field("item", binary(), true)), false), field("views", list(field("item", binary(), true)), false), field("scalar_functions", list(field("item", binary(), true)), false), field("aggregate_functions", list(field("item", binary(), true)), false), field("table_functions", list(field("item", binary(), true)), false), field("scalar_macros", list(field("item", binary(), true)), false), field("table_macros", list(field("item", binary(), true)), false), field("indexes", list(field("item", binary(), true)), false)]), true)), false),
+]);
+
 // Origin: method 'catalog_copy_from_formats' result
 export const CatalogCopyFromFormatsResultSchema = schema([
   field("items", list(field("item", binary(), true)), false),
@@ -833,6 +856,12 @@ export const CatalogAttachParamsSchema = schema([
 // Origin: method 'catalog_catalogs' params
 export const CatalogCatalogsParamsSchema = schema([]);
 
+// Origin: method 'catalog_contents' params
+export const CatalogContentsParamsSchema = schema([
+  field("attach_opaque_data", binary(), false),
+  field("if_none_match", utf8(), true),
+]);
+
 // Origin: method 'catalog_copy_from_formats' params
 export const CatalogCopyFromFormatsParamsSchema = schema([
   field("attach_opaque_data", binary(), false),

package/src/generated/vgi-protocol-types.ts

@@ -0,0 +1,126 @@
+// ============================================================================
+// GENERATED by vgi.codegen.ts_types. DO NOT EDIT BY HAND.
+//
+// Generator: python -m vgi.codegen.ts_types v1
+// Content hash: d240510f013b
+//
+// To regenerate:
+//   uv run --project ~/Development/vgi-python python scripts/regen_generated.py
+// ============================================================================
+
+import { encodeASD, decodeASD } from "../codec/asd.js";
+import {
+  CatalogAttachResultSchema,
+  CatalogContentsResultSchema,
+  SchemaContentsSchema,
+} from "./vgi-protocol-schemas.js";
+import type { CatalogAttachResult, CatalogContentsResponse, SchemaContents } from "./vgi-client.js";
+export type { CatalogAttachResult, CatalogContentsResponse, SchemaContents };
+
+// ----------------------------------------------------------------------------
+// CatalogAttachResult  (schema: CatalogAttachResultSchema)
+// ----------------------------------------------------------------------------
+
+/** Fields of `CatalogAttachResult` that have a protocol default. */
+export type CatalogAttachResultDefaultedField =
+  | "attach_opaque_data_required"
+  | "default_schema"
+  | "settings"
+  | "secret_types"
+  | "attach_catalogs"
+  | "comment"
+  | "tags"
+  | "supports_column_statistics"
+  | "global_functions"
+  | "global_function_prefix"
+  | "supports_catalog_contents";
+/** `CatalogAttachResult` with every field that has a protocol default optional. */
+export type CatalogAttachResultInit = Omit<CatalogAttachResult, CatalogAttachResultDefaultedField> & Partial<Pick<CatalogAttachResult, CatalogAttachResultDefaultedField>>;
+
+/** Build a complete `CatalogAttachResult`, filling the protocol defaults, in wire order. */
+export function buildCatalogAttachResult(init: CatalogAttachResultInit): CatalogAttachResult {
+  return {
+    attach_opaque_data: init.attach_opaque_data,
+    supports_transactions: init.supports_transactions,
+    supports_time_travel: init.supports_time_travel,
+    catalog_version_frozen: init.catalog_version_frozen,
+    catalog_version: init.catalog_version,
+    attach_opaque_data_required: init.attach_opaque_data_required ?? true,
+    default_schema: init.default_schema ?? "main",
+    settings: init.settings ?? [],
+    secret_types: init.secret_types ?? [],
+    attach_catalogs: init.attach_catalogs ?? [],
+    comment: init.comment ?? null,
+    tags: init.tags ?? {},
+    supports_column_statistics: init.supports_column_statistics ?? false,
+    global_functions: init.global_functions ?? [],
+    global_function_prefix: init.global_function_prefix ?? "",
+    resolved_data_version: init.resolved_data_version ?? null,
+    resolved_implementation_version: init.resolved_implementation_version ?? null,
+    supports_catalog_contents: init.supports_catalog_contents ?? false,
+  };
+}
+
+export const encodeCatalogAttachResult = (v: CatalogAttachResult): Uint8Array => encodeASD(CatalogAttachResultSchema, v);
+export const decodeCatalogAttachResult = (b: Uint8Array): CatalogAttachResult => decodeASD<CatalogAttachResult>(CatalogAttachResultSchema, b);
+
+// ----------------------------------------------------------------------------
+// SchemaContents  (schema: SchemaContentsSchema)
+// ----------------------------------------------------------------------------
+
+/** Fields of `SchemaContents` that have a protocol default. */
+export type SchemaContentsDefaultedField =
+  | "tables"
+  | "views"
+  | "scalar_functions"
+  | "aggregate_functions"
+  | "table_functions"
+  | "scalar_macros"
+  | "table_macros"
+  | "indexes";
+/** `SchemaContents` with every field that has a protocol default optional. */
+export type SchemaContentsInit = Omit<SchemaContents, SchemaContentsDefaultedField> & Partial<Pick<SchemaContents, SchemaContentsDefaultedField>>;
+
+/** Build a complete `SchemaContents`, filling the protocol defaults, in wire order. */
+export function buildSchemaContents(init: SchemaContentsInit): SchemaContents {
+  return {
+    path: init.path,
+    schema: init.schema,
+    tables: init.tables ?? [],
+    views: init.views ?? [],
+    scalar_functions: init.scalar_functions ?? [],
+    aggregate_functions: init.aggregate_functions ?? [],
+    table_functions: init.table_functions ?? [],
+    scalar_macros: init.scalar_macros ?? [],
+    table_macros: init.table_macros ?? [],
+    indexes: init.indexes ?? [],
+  };
+}
+
+export const encodeSchemaContents = (v: SchemaContents): Uint8Array => encodeASD(SchemaContentsSchema, v);
+export const decodeSchemaContents = (b: Uint8Array): SchemaContents => decodeASD<SchemaContents>(SchemaContentsSchema, b);
+
+// ----------------------------------------------------------------------------
+// CatalogContentsResponse  (schema: CatalogContentsResultSchema)
+// ----------------------------------------------------------------------------
+
+/** Fields of `CatalogContentsResponse` that have a protocol default. */
+export type CatalogContentsResponseDefaultedField =
+  | "etag"
+  | "not_modified"
+  | "schemas";
+/** `CatalogContentsResponse` with every field that has a protocol default optional. */
+export type CatalogContentsResponseInit = Omit<CatalogContentsResponse, CatalogContentsResponseDefaultedField> & Partial<Pick<CatalogContentsResponse, CatalogContentsResponseDefaultedField>>;
+
+/** Build a complete `CatalogContentsResponse`, filling the protocol defaults, in wire order. */
+export function buildCatalogContentsResponse(init: CatalogContentsResponseInit): CatalogContentsResponse {
+  return {
+    catalog_version: init.catalog_version,
+    etag: init.etag ?? null,
+    not_modified: init.not_modified ?? false,
+    schemas: init.schemas ?? [],
+  };
+}
+
+export const encodeCatalogContentsResponse = (v: CatalogContentsResponse): Uint8Array => encodeASD(CatalogContentsResultSchema, v);
+export const decodeCatalogContentsResponse = (b: Uint8Array): CatalogContentsResponse => decodeASD<CatalogContentsResponse>(CatalogContentsResultSchema, b);

package/src/http/fetch.ts

@@ -25,9 +25,10 @@ import {
 import { arrowStateSerializer } from "../protocol/state-serializer.js";
 import { buildVgiProtocol, type ProtocolConfig } from "../protocol/dispatch.js";
 import { createLandingRoutes, type LandingInfo } from "./landing.js";
+import { buildRpcServer, type HostingOptions } from "../rpc-server.js";
 import { setRequestAuthScope, type RequestAuthHolder } from "../request-auth.js";
 
-export interface VgiFetchOptions {
+export interface VgiFetchOptions extends HostingOptions {
   /** Wire-protocol config (registry + catalogInterface). */
   protocol: ProtocolConfig;
   /** HMAC key for state-token signing. Pass a stable, secret 32-byte key
@@ -197,7 +198,14 @@ export function createVgiFetch(opts: VgiFetchOptions): (req: Request) => Promise
     ...opts.protocol,
   });
 
-  const handler = createHttpHandler(protocol, {
+  // The same builder every other transport uses: `vgi.v2`, the worker's
+  // hostedProtocols(), reflection, and -- HTTP being the transport that
+  // authenticates callers -- vgi_rpc.Identity.v1 when the worker opts in.
+  // Built at construction, so a worker that opts into introspection without an
+  // allowlist fails here rather than serving traffic.
+  const server = buildRpcServer(protocol, opts, { transport: "http", serverId });
+
+  const handler = createHttpHandler(server, {
     prefix,
     serverId,
     tokenKey: opts.signingKey,

package/src/index.core.ts

@@ -77,9 +77,9 @@ export {
 export type { VgiFunction, FunctionMeta, StreamHandlers, FunctionExample, HandlerState } from "./functions/types.js";
 
 // Catalog
-export { CatalogInterface, type CatalogAttachResult, type SchemaInfo, encodeSchemaInfo, decodeSchemaInfo, type TableInfo, encodeTableInfo, decodeTableInfo, type ViewInfo, encodeViewInfo, decodeViewInfo, type CatalogInfo, encodeCatalogInfo, decodeCatalogInfo, type FunctionInfo, encodeFunctionInfo, decodeFunctionInfo, type FunctionInfoOptions, type MacroInfo, encodeMacroInfo, decodeMacroInfo, type MacroType, type CopyFromFormatInfo, encodeCopyFromFormatInfo, type AttachOpaqueData, type TransactionOpaqueData, buildScanBranchesResult, encodeFormatOptions, type ScanBranchInput } from "./catalog/interface.js";
+export { CatalogInterface, type CatalogAttachResult, type CatalogAttachResultInit, buildCatalogAttachResult, type SchemaContentsInfo, type CatalogContentsResult, type SchemaInfo, encodeSchemaInfo, decodeSchemaInfo, type TableInfo, encodeTableInfo, decodeTableInfo, type ViewInfo, encodeViewInfo, decodeViewInfo, type CatalogInfo, encodeCatalogInfo, decodeCatalogInfo, type FunctionInfo, encodeFunctionInfo, decodeFunctionInfo, type FunctionInfoOptions, type MacroInfo, encodeMacroInfo, decodeMacroInfo, type MacroType, type CopyFromFormatInfo, encodeCopyFromFormatInfo, type AttachOpaqueData, type TransactionOpaqueData, buildScanBranchesResult, encodeFormatOptions, type ScanBranchInput } from "./catalog/interface.js";
 export type { CatalogDescriptor, SchemaDescriptor, TableDescriptor, ViewDescriptor, MacroDescriptor, SettingDescriptor, SecretTypeDescriptor, ForeignKeyDef, DefaultValue } from "./catalog/descriptors.js";
-export { ReadOnlyCatalogInterface } from "./catalog/read-only.js";
+export { ReadOnlyCatalogInterface, READ_ONLY_ITEM_ATTACH_ID } from "./catalog/read-only.js";
 export { CompositeCatalogInterface } from "./catalog/composite.js";
 export { FunctionRegistry } from "./functions/registry.js";
 
@@ -309,4 +309,23 @@ export type {
 export { str, bytes, int, int32, float, float32, bool, toSchema, OutputCollector, AuthContext } from "@query-farm/vgi-rpc";
 export { subprocessConnect, httpConnect, tcpConnect } from "@query-farm/vgi-rpc";
 export type { RpcClient, StreamSession, LogMessage } from "@query-farm/vgi-rpc";
+
+// Hosting additional protocols and opting into vgi_rpc.Identity.v1. The errors
+// are re-exported so a worker's resolveToken/mintGrant can throw the right one:
+// AuthUnavailableError (or IdentityUnavailableError) for "could not find out",
+// GrantRefusedError to decline a grant.
+export {
+  buildRpcServer,
+  INTROSPECT_PRINCIPALS_ENV,
+  type BuildRpcServerOptions,
+  type HostingOptions,
+  type ServerTransport,
+} from "./rpc-server.js";
+export {
+  AuthUnavailableError,
+  GrantRefusedError,
+  IdentityUnavailableError,
+  StatusError,
+} from "@query-farm/vgi-rpc";
+export type { GrantMinter, IssuedGrant, TokenIdentity, TokenResolver } from "@query-farm/vgi-rpc";
 export { normalizeSchemaPath, schemaPathDisplay, schemaPathKey, schemaPathsEqual, type SchemaPath } from "./schema-path.js";

package/src/protocol/dispatch.ts

@@ -57,7 +57,7 @@ export interface ProtocolConfig {
 export const VGI_PROTOCOL_NAME = "vgi.v2";
 
 export function buildVgiProtocol(config: ProtocolConfig): Protocol {
-  const protocol = new Protocol(VGI_PROTOCOL_NAME, { protocolVersion: "2.0.0" });
+  const protocol = new Protocol(VGI_PROTOCOL_NAME, { protocolVersion: "2.1.0" });
 
   registerFunctionMethods(protocol, {
     registry: config.registry,

package/src/protocol/handlers/catalog/admin.ts

@@ -4,12 +4,20 @@
 
 import { type VgiSchema, schema, type VgiField, field, type VgiDataType, binary, utf8, bool } from "../../../arrow/index.js";
 import { Protocol, type CallContext } from "@query-farm/vgi-rpc";
-import { encodeSchemaInfo, encodeTableInfo, encodeViewInfo, encodeCatalogInfo } from "../../../generated/vgi-client.js";
+import {
+  encodeSchemaInfo,
+  encodeTableInfo,
+  encodeViewInfo,
+  encodeCatalogInfo,
+} from "../../../generated/vgi-client.js";
+import { buildCatalogAttachResult } from "../../../generated/vgi-protocol-types.js";
+import { serveCatalogContents } from "./contents.js";
 import { encodeFunctionInfoOnce } from "../../../catalog/item-encoding.js";
 import { encodeCopyFromFormatInfo } from "../../../catalog/interface.js";
 import {
   CatalogAttachParamsSchema,
   CatalogAttachResultSchema,
+  CatalogContentsParamsSchema,
   CatalogCatalogsParamsSchema,
   CatalogCatalogsResultSchema,
   CatalogCopyFromFormatsParamsSchema,
@@ -105,33 +113,19 @@ export function registerCatalogAdminMethods(protocol: Protocol, getCatalog: GetC
         (ctx as CallContext | undefined)?.auth,
         signingKey,
       );
-      return wrapResult({
+      // The generated builder emits every column of the pinned
+      // CatalogAttachResult schema, filling vgi-python's defaults for any a
+      // catalog left out (supports_catalog_contents=false: the client then
+      // keeps to the per-schema RPCs).
+      return wrapResult(buildCatalogAttachResult({
+        ...result,
         attach_opaque_data: sealedAttach,
-        supports_transactions: result.supports_transactions,
-        supports_time_travel: result.supports_time_travel,
-        catalog_version_frozen: result.catalog_version_frozen,
-        catalog_version: result.catalog_version,
-        attach_opaque_data_required: result.attach_opaque_data_required ?? true,
-        default_schema: result.default_schema ?? "main",
-        settings: result.settings ?? [],
-        secret_types: result.secret_types ?? [],
-        attach_catalogs: result.attach_catalogs ?? [],
-        comment: result.comment ?? null,
-        tags: result.tags ?? {},
-        // True so DuckDB will route catalog_table_column_statistics_get RPCs
-        // to our handler for tables whose TableInfo.supports_column_statistics
-        // is also true. Catalogs that never serve column stats can override
-        // this in attach() via CatalogAttachResult.supports_column_statistics.
+        // SDK default, unlike vgi-python's false: true so DuckDB will route
+        // catalog_table_column_statistics_get RPCs to our handler for tables
+        // whose TableInfo.supports_column_statistics is also true. Catalogs
+        // that never serve column stats set it false in attach().
         supports_column_statistics: result.supports_column_statistics ?? true,
-        // Protocol 1.3.0: functions the worker asks the client to publish into
-        // its global namespace. Empty unless the catalog advertises them —
-        // but the columns must still be present, since the extension pins the
-        // full CatalogAttachResult field list on the response schema.
-        global_functions: result.global_functions ?? [],
-        global_function_prefix: result.global_function_prefix ?? "",
-        resolved_data_version: result.resolved_data_version ?? null,
-        resolved_implementation_version: result.resolved_implementation_version ?? null,
-      }, CatalogAttachResultSchema);
+      }), CatalogAttachResultSchema);
     },
   });
 
@@ -247,6 +241,21 @@ export function registerCatalogAdminMethods(protocol: Protocol, getCatalog: GetC
     },
   });
 
+  // catalog_contents — every schema and all of its contents in one result,
+  // for a client whose attach result set supports_catalog_contents. Takes no
+  // transaction: the client caches the answer for the whole attach, so it is
+  // the committed catalog at catalog_version. `if_none_match` revalidates a
+  // snapshot the client holds (etag / not_modified); see ./contents.ts for the
+  // rules, the content-hash etag and the frozen-catalog cache.
+  catalogUnary(protocol, signingKey, "catalog_contents", {
+    params: CatalogContentsParamsSchema,
+    result: RESULT_BINARY_SCHEMA,
+    handler: async (params) => {
+      const ifNoneMatch = params.if_none_match == null ? null : String(params.if_none_match);
+      return serveCatalogContents(getCatalog(), toUint8Array(params.attach_opaque_data), ifNoneMatch);
+    },
+  });
+
   // catalog_copy_from_formats — catalog-level (not schema-scoped). Lists the
   // custom COPY ... FROM formats this catalog advertises; empty list when none.
   catalogUnary(protocol, signingKey, "catalog_copy_from_formats", {

package/src/protocol/handlers/catalog/contents.ts

@@ -0,0 +1,162 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// SPDX-License-Identifier: LicenseRef-QueryFarm-Source-Available-1.0
+
+// catalog_contents: the worker side of the protocol 2.1.0 bulk enumeration,
+// with etag revalidation and the frozen-catalog response cache. Mirrors
+// vgi-python's Worker.catalog_contents / _catalog_contents_response.
+
+import {
+  encodeSchemaInfo,
+  encodeTableInfo,
+  encodeViewInfo,
+  encodeMacroInfo,
+  encodeIndexInfo,
+} from "../../../generated/vgi-client.js";
+import {
+  buildCatalogContentsResponse,
+  buildSchemaContents,
+  type CatalogContentsResponse,
+  type SchemaContents,
+} from "../../../generated/vgi-protocol-types.js";
+import { CatalogContentsResultSchema } from "../../../generated/vgi-protocol-schemas.js";
+import { encodeFunctionInfoOnce } from "../../../catalog/item-encoding.js";
+import type { AttachOpaqueData, CatalogInterface } from "../../../catalog/interface.js";
+import { catalogContentsDigest } from "../../../catalog/contents-digest.js";
+import { schemaPathKey } from "../../../schema-path.js";
+import { wrapResult } from "../shared.js";
+
+type Wire = { result: Uint8Array };
+
+/** One cached answer per catalog instance, valid for one catalog version. */
+interface ContentsSnapshot {
+  version: number;
+  etag: string | null;
+  wire: Wire;
+}
+
+/**
+ * Cached catalog_contents responses, keyed by the owning catalog instance
+ * (weak, so a dropped catalog takes its snapshot with it). Holds the build
+ * promise, so concurrent first calls build once.
+ */
+const CACHE = new WeakMap<CatalogInterface, Promise<ContentsSnapshot>>();
+
+/**
+ * Ask the catalog for its contents and shape the typed wire response.
+ *
+ * Enforces the revalidation rules: `not_modified` needs an etag equal to
+ * `ifNoneMatch` and no schemas; a catalog with no etag never yields
+ * `not_modified` (and so ignores `ifNoneMatch`). Validates the schema paths
+ * (unique, parent present) and orders them parent-first. Every item is
+ * encoded with the SAME encoder its per-schema RPC uses, so items are
+ * byte-identical to catalog_schemas / catalog_schema_contents_* items.
+ */
+export async function buildCatalogContents(
+  cat: CatalogInterface,
+  owner: CatalogInterface,
+  attach: AttachOpaqueData,
+  version: number,
+  ifNoneMatch: string | null,
+): Promise<CatalogContentsResponse> {
+  const result = await cat.catalogContents(attach, ifNoneMatch);
+  const etag0 = result.etag ?? null;
+  if (result.not_modified) {
+    if (etag0 === null || ifNoneMatch === null || etag0 !== ifNoneMatch) {
+      throw new Error(
+        "catalog_contents returned not_modified, but only a catalog whose etag equals " +
+          "if_none_match may (and it must return that etag)",
+      );
+    }
+    if (result.schemas && result.schemas.length > 0) {
+      throw new Error("catalog_contents returned not_modified with schemas; it must return none");
+    }
+    return buildCatalogContentsResponse({ catalog_version: version, etag: etag0, not_modified: true });
+  }
+
+  const infos = [...(result.schemas ?? [])];
+  const keys = infos.map((c) => schemaPathKey(c.schema.path));
+  const keySet = new Set(keys);
+  if (keySet.size !== keys.length) throw new Error("catalog_contents returned duplicate schema paths");
+  for (const c of infos) {
+    if (c.schema.path.length > 1 && !keySet.has(schemaPathKey(c.schema.path.slice(0, -1)))) {
+      throw new Error(`catalog_contents returned schema path ${JSON.stringify(c.schema.path)} without its parent`);
+    }
+  }
+
+  // Same parent-before-child order catalog_schemas guarantees (stable sort).
+  const schemas: SchemaContents[] = infos
+    .sort((a, b) => a.schema.path.length - b.schema.path.length)
+    .map((c) =>
+      buildSchemaContents({
+        path: [...c.schema.path],
+        schema: encodeSchemaInfo(c.schema),
+        tables: c.tables.map((t) => encodeTableInfo(t)),
+        views: c.views.map((v) => encodeViewInfo(v)),
+        scalar_functions: c.scalar_functions.map((f) => encodeFunctionInfoOnce(f)),
+        aggregate_functions: c.aggregate_functions.map((f) => encodeFunctionInfoOnce(f)),
+        table_functions: c.table_functions.map((f) => encodeFunctionInfoOnce(f)),
+        scalar_macros: c.scalar_macros.map((m) => encodeMacroInfo(m)),
+        table_macros: c.table_macros.map((m) => encodeMacroInfo(m)),
+        indexes: c.indexes.map((i) => encodeIndexInfo(i)),
+      }),
+    );
+  let etag = etag0;
+  if (etag === null && owner.catalogContentsEtag === "content-hash") {
+    etag = await catalogContentsDigest(schemas);
+  }
+  if (etag !== null && ifNoneMatch !== null && etag === ifNoneMatch) {
+    return buildCatalogContentsResponse({ catalog_version: version, etag, not_modified: true });
+  }
+  return buildCatalogContentsResponse({ catalog_version: version, etag, schemas });
+}
+
+/**
+ * Serve one catalog_contents call (the attach value is already opened).
+ *
+ * Caching: a catalog whose `catalogContentsCacheable()` is true (by default:
+ * version frozen and contents attach-independent; ReadOnlyCatalogInterface) is
+ * built once per (catalog instance, version); every later call reuses the same
+ * serialized response bytes. A conditional call matching the cached etag is
+ * answered `not_modified` without touching the snapshot.
+ */
+export async function serveCatalogContents(
+  cat: CatalogInterface,
+  attach: AttachOpaqueData,
+  ifNoneMatch: string | null,
+): Promise<Wire> {
+  const owner = cat.catalogContentsOwner(attach);
+  const version = Number(await cat.version(attach));
+  if (owner.catalogContentsCacheable()) {
+    let pending = CACHE.get(owner);
+    let snapshot = pending ? await pending.catch(() => null) : null;
+    if (!snapshot || snapshot.version !== version) {
+      pending = (async () => {
+        const built = await buildCatalogContents(cat, owner, attach, version, null);
+        return {
+          version,
+          etag: built.etag ?? null,
+          wire: wrapResult(built, CatalogContentsResultSchema),
+        };
+      })();
+      CACHE.set(owner, pending);
+      try {
+        snapshot = await pending;
+      } catch (err) {
+        // A failed build is not cached: the next call tries again.
+        if (CACHE.get(owner) === pending) CACHE.delete(owner);
+        throw err;
+      }
+    }
+    if (ifNoneMatch !== null && snapshot.etag !== null && ifNoneMatch === snapshot.etag) {
+      return wrapResult(
+        buildCatalogContentsResponse({ catalog_version: version, etag: snapshot.etag, not_modified: true }),
+        CatalogContentsResultSchema,
+      );
+    }
+    return snapshot.wire;
+  }
+  return wrapResult(
+    await buildCatalogContents(cat, owner, attach, version, ifNoneMatch),
+    CatalogContentsResultSchema,
+  );
+}