@query-farm/vgi 0.37.1 → 0.39.0

package/dist/index.js

@@ -7035,7 +7035,84 @@ function schemaPathDisplay(path) {
 // src/codec/asd.ts
 init_arrow();
 function encodeASD(schema, obj) {
-  return serializeBatch(batchFromRows([obj], schema));
+  return serializeBatch(batchFromRows([sortMapsForSchema(schema, obj)], schema));
+}
+function compareCodePoints(a, b) {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0;i < n; i++) {
+    const x = a.charCodeAt(i);
+    const y = b.charCodeAt(i);
+    if (x === y)
+      continue;
+    const xs = x >= 55296 && x <= 57343;
+    const ys = y >= 55296 && y <= 57343;
+    if (xs !== ys)
+      return xs ? 1 : -1;
+    return x - y;
+  }
+  return a.length - b.length;
+}
+function mapPairs(raw) {
+  if (Array.isArray(raw))
+    return raw.map((e) => Array.isArray(e) ? [e[0], e[1]] : [e?.key, e?.value]);
+  if (raw instanceof Map)
+    return Array.from(raw.entries());
+  if (typeof raw[Symbol.iterator] === "function")
+    return Array.from(raw);
+  return Object.entries(raw);
+}
+function compareKeys(a, b) {
+  if (typeof a === "string" && typeof b === "string")
+    return compareCodePoints(a, b);
+  if ((typeof a === "number" || typeof a === "bigint") && (typeof b === "number" || typeof b === "bigint")) {
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+  return compareCodePoints(String(a), String(b));
+}
+var HAS_MAP = new WeakMap;
+function typeHasMap(type) {
+  const cached = HAS_MAP.get(type);
+  if (cached !== undefined)
+    return cached;
+  let has = isMap(type);
+  if (!has && (isList(type) || isStruct(type))) {
+    has = type.children.some((c) => typeHasMap(c.type));
+  }
+  HAS_MAP.set(type, has);
+  return has;
+}
+function sortMapsForType(type, value) {
+  if (value == null || !typeHasMap(type))
+    return value;
+  if (isMap(type)) {
+    const entries = type.children[0].type;
+    const valueType = entries.children[1].type;
+    return mapPairs(value).map(([k, v]) => [k, sortMapsForType(valueType, v)]).sort((x, y) => compareKeys(x[0], y[0]));
+  }
+  if (isList(type)) {
+    const child = type.children[0].type;
+    return Array.from(value, (v) => sortMapsForType(child, v));
+  }
+  if (isStruct(type)) {
+    const out = { ...value };
+    for (const cf of type.children)
+      out[cf.name] = sortMapsForType(cf.type, value[cf.name]);
+    return out;
+  }
+  return value;
+}
+function sortMapsForSchema(schema, obj) {
+  let out = null;
+  for (const f of schema.fields) {
+    if (!typeHasMap(f.type))
+      continue;
+    const v = obj[f.name];
+    if (v == null)
+      continue;
+    out ??= { ...obj };
+    out[f.name] = sortMapsForType(f.type, v);
+  }
+  return out ?? obj;
 }
 function decodeASD(schema, bytes) {
   const batch = deserializeBatch(bytes);
@@ -7062,21 +7139,23 @@ function normalizeValue(raw, type) {
     return out;
   }
   if (isMap(type)) {
+    const entries = type.children[0].type;
+    const valueType = entries.children[1].type;
     const out = {};
+    const put = (k, v) => {
+      out[String(k)] = normalizeValue(v, valueType);
+    };
     if (raw[Symbol.iterator]) {
       for (const entry of raw) {
         if (Array.isArray(entry)) {
-          out[String(entry[0])] = String(entry[1] ?? "");
+          put(entry[0], entry[1]);
         } else if (entry && typeof entry === "object") {
-          const k = entry.key ?? entry[0];
-          const v = entry.value ?? entry[1];
-          out[String(k)] = v == null ? "" : String(v);
+          put(entry.key ?? entry[0], entry.value ?? entry[1]);
         }
       }
     } else if (typeof raw === "object") {
-      for (const [k, v] of Object.entries(raw)) {
-        out[String(k)] = v == null ? "" : String(v);
-      }
+      for (const [k, v] of Object.entries(raw))
+        put(k, v);
     }
     return out;
   }
@@ -7292,6 +7371,18 @@ var ForeignKeyInfoSchema = schema2([
   field2("referenced_table", utf82(), false),
   field2("referenced_schema_path", list2(field2("item", utf82(), true)), false)
 ]);
+var SchemaContentsSchema = schema2([
+  field2("path", list2(field2("item", utf82(), true)), false),
+  field2("schema", binary2(), false),
+  field2("tables", list2(field2("item", binary2(), true)), false),
+  field2("views", list2(field2("item", binary2(), true)), false),
+  field2("scalar_functions", list2(field2("item", binary2(), true)), false),
+  field2("aggregate_functions", list2(field2("item", binary2(), true)), false),
+  field2("table_functions", list2(field2("item", binary2(), true)), false),
+  field2("scalar_macros", list2(field2("item", binary2(), true)), false),
+  field2("table_macros", list2(field2("item", binary2(), true)), false),
+  field2("indexes", list2(field2("item", binary2(), true)), false)
+]);
 var AggregateBindRequestSchema = schema2([
   field2("function_name", utf82(), false),
   field2("arguments", binary2(), false),
@@ -7614,11 +7705,18 @@ var CatalogAttachResultSchema = schema2([
   field2("global_functions", list2(field2("item", binary2(), true)), false),
   field2("global_function_prefix", utf82(), false),
   field2("resolved_data_version", utf82(), true),
-  field2("resolved_implementation_version", utf82(), true)
+  field2("resolved_implementation_version", utf82(), true),
+  field2("supports_catalog_contents", bool2(), false)
 ]);
 var CatalogCatalogsResultSchema = schema2([
   field2("items", list2(field2("item", binary2(), true)), false)
 ]);
+var CatalogContentsResultSchema = schema2([
+  field2("catalog_version", int642(), false),
+  field2("etag", utf82(), true),
+  field2("not_modified", bool2(), false),
+  field2("schemas", list2(field2("item", struct2([field2("path", list2(field2("item", utf82(), true)), false), field2("schema", binary2(), false), field2("tables", list2(field2("item", binary2(), true)), false), field2("views", list2(field2("item", binary2(), true)), false), field2("scalar_functions", list2(field2("item", binary2(), true)), false), field2("aggregate_functions", list2(field2("item", binary2(), true)), false), field2("table_functions", list2(field2("item", binary2(), true)), false), field2("scalar_macros", list2(field2("item", binary2(), true)), false), field2("table_macros", list2(field2("item", binary2(), true)), false), field2("indexes", list2(field2("item", binary2(), true)), false)]), true)), false)
+]);
 var CatalogCopyFromFormatsResultSchema = schema2([
   field2("items", list2(field2("item", binary2(), true)), false)
 ]);
@@ -7737,6 +7835,10 @@ var CatalogAttachParamsSchema = schema2([
   field2("request", binary2(), false)
 ]);
 var CatalogCatalogsParamsSchema = schema2([]);
+var CatalogContentsParamsSchema = schema2([
+  field2("attach_opaque_data", binary2(), false),
+  field2("if_none_match", utf82(), true)
+]);
 var CatalogCopyFromFormatsParamsSchema = schema2([
   field2("attach_opaque_data", binary2(), false),
   field2("transaction_opaque_data", binary2(), true)
@@ -8067,12 +8169,59 @@ var TableFunctionStatisticsParamsSchema = schema2([
   field2("request", binary2(), false)
 ]);
 
+// src/generated/vgi-protocol-types.ts
+function buildCatalogAttachResult(init) {
+  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
+  };
+}
+function buildSchemaContents(init) {
+  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 ?? []
+  };
+}
+function buildCatalogContentsResponse(init) {
+  return {
+    catalog_version: init.catalog_version,
+    etag: init.etag ?? null,
+    not_modified: init.not_modified ?? false,
+    schemas: init.schemas ?? []
+  };
+}
+var decodeCatalogContentsResponse = (b) => decodeASD(CatalogContentsResultSchema, b);
 // src/generated/vgi-client.ts
 var encodeCatalogInfo = (v) => encodeASD(CatalogInfoSchema, v);
 var decodeCatalogInfo = (b) => decodeASD(CatalogInfoSchema, b);
 var encodeFunctionInfo = (v) => encodeASD(FunctionInfoSchema, v);
 var decodeFunctionInfo = (b) => decodeASD(FunctionInfoSchema, b);
 var encodeIndexInfo = (v) => encodeASD(IndexInfoSchema, v);
+var decodeIndexInfo = (b) => decodeASD(IndexInfoSchema, b);
 var encodeMacroInfo = (v) => encodeASD(MacroInfoSchema, v);
 var decodeMacroInfo = (b) => decodeASD(MacroInfoSchema, b);
 var encodeSchemaInfo = (v) => encodeASD(SchemaInfoSchema, v);
@@ -8215,6 +8364,9 @@ function isPromise(v) {
 }
 
 class CatalogInterface {
+  catalogContentsEtag = null;
+  catalogContentsAttachIndependent = false;
+  catalogVersionFrozen = false;
   catalogNameForAttach(_attachOpaqueData) {
     const names = this.catalogs();
     return names.length === 1 ? names[0] : null;
@@ -8332,6 +8484,42 @@ class CatalogInterface {
   copyFromFormats(attachOpaqueData, transactionOpaqueData) {
     return [];
   }
+  async catalogContents(attachOpaqueData, _ifNoneMatch) {
+    const schemas = await this.schemas(attachOpaqueData, undefined);
+    const contents = await Promise.all(schemas.map(async (schema) => {
+      const counts = schema.estimated_object_count ?? {};
+      const path = schema.path;
+      const kind = async (countKey, list) => (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,
+        views,
+        scalar_functions: scalarFunctions,
+        aggregate_functions: aggregateFunctions,
+        table_functions: tableFunctions,
+        scalar_macros: scalarMacros,
+        table_macros: tableMacros,
+        indexes
+      };
+    }));
+    return { schemas: contents };
+  }
+  catalogContentsCacheable() {
+    return this.catalogContentsAttachIndependent && this.catalogVersionFrozen;
+  }
+  catalogContentsOwner(_attachOpaqueData) {
+    return this;
+  }
   transactionBegin(attachOpaqueData) {
     return null;
   }
@@ -8594,17 +8782,25 @@ function encodeFunctionInfoOnce(info) {
 }
 
 // src/catalog/read-only.ts
+var READ_ONLY_ITEM_ATTACH_ID = new TextEncoder().encode("readonly-catalog-");
+
 class ReadOnlyCatalogInterface extends CatalogInterface {
+  supportsCatalogContents = true;
+  catalogVersionFrozen = true;
+  perAttachItemIds = false;
+  catalogContentsAttachIndependent = true;
   _descriptor;
   _registry;
   _attachments = new Map;
   _version = 1;
   _functionListings = new Map;
   _functionInfos = new Map;
-  constructor(descriptor, registry) {
+  constructor(descriptor, registry, options = {}) {
     super();
     this._descriptor = descriptor;
     this._registry = registry;
+    if (options.perAttachItemIds)
+      this.perAttachItemIds = true;
     for (const sch of descriptor.schemas ?? []) {
       for (const fn of sch.functions ?? [])
         registry.registerInSchema(fn, schemaDescriptorPath(sch), descriptor.name);
@@ -8652,7 +8848,7 @@ class ReadOnlyCatalogInterface extends CatalogInterface {
     const secretTypes = (this._descriptor.secretTypes ?? []).map((s) => serializeSecretType(s));
     const attachCatalogs = (this._descriptor.attachCatalogs ?? []).map((c) => encodeAttachCatalogInfo(c));
     const hasTimeTravel = this._descriptor.schemas.some((s) => s.tables?.some((t) => t.supportsTimeTravel) ?? false);
-    return {
+    return buildCatalogAttachResult({
       attach_opaque_data: attachOpaqueData,
       supports_transactions: false,
       supports_time_travel: hasTimeTravel,
@@ -8669,8 +8865,9 @@ class ReadOnlyCatalogInterface extends CatalogInterface {
       global_functions: this._globalFunctionInfos().map(encodeFunctionInfoOnce),
       global_function_prefix: this._descriptor.globalFunctionPrefix ?? "",
       resolved_data_version: null,
-      resolved_implementation_version: null
-    };
+      resolved_implementation_version: null,
+      supports_catalog_contents: this.supportsCatalogContents
+    });
   }
   detach(attachOpaqueData) {
     for (const [name, id] of this._attachments) {
@@ -8683,9 +8880,15 @@ class ReadOnlyCatalogInterface extends CatalogInterface {
   version(attachOpaqueData, transactionOpaqueData) {
     return this._version;
   }
+  itemAttachId(attachOpaqueData) {
+    return this.perAttachItemIds ? attachOpaqueData : READ_ONLY_ITEM_ATTACH_ID;
+  }
+  catalogContentsCacheable() {
+    return super.catalogContentsCacheable() && !this.perAttachItemIds;
+  }
   schemas(attachOpaqueData, transactionOpaqueData) {
     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 ?? {},
@@ -8717,7 +8920,7 @@ class ReadOnlyCatalogInterface extends CatalogInterface {
     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 ?? {},
@@ -8743,7 +8946,7 @@ 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
           };
@@ -9417,6 +9620,72 @@ class CompositeCatalogInterface extends CatalogInterface {
   async macroGet(attachOpaqueData, schemaPath, name, transactionOpaqueData) {
     return await this._route(attachOpaqueData).macroGet(attachOpaqueData, schemaPath, name, transactionOpaqueData);
   }
+  async schemaCreate(...args) {
+    await this._route(args[0]).schemaCreate(...args);
+  }
+  async schemaDrop(...args) {
+    await this._route(args[0]).schemaDrop(...args);
+  }
+  async tableCreate(...args) {
+    await this._route(args[0]).tableCreate(...args);
+  }
+  async tableDrop(...args) {
+    await this._route(args[0]).tableDrop(...args);
+  }
+  async tableCommentSet(...args) {
+    await this._route(args[0]).tableCommentSet(...args);
+  }
+  async tableRename(...args) {
+    await this._route(args[0]).tableRename(...args);
+  }
+  async tableColumnAdd(...args) {
+    await this._route(args[0]).tableColumnAdd(...args);
+  }
+  async tableColumnDrop(...args) {
+    await this._route(args[0]).tableColumnDrop(...args);
+  }
+  async tableColumnRename(...args) {
+    await this._route(args[0]).tableColumnRename(...args);
+  }
+  async tableColumnDefaultSet(...args) {
+    await this._route(args[0]).tableColumnDefaultSet(...args);
+  }
+  async tableColumnDefaultDrop(...args) {
+    await this._route(args[0]).tableColumnDefaultDrop(...args);
+  }
+  async tableColumnTypeChange(...args) {
+    await this._route(args[0]).tableColumnTypeChange(...args);
+  }
+  async tableNotNullSet(...args) {
+    await this._route(args[0]).tableNotNullSet(...args);
+  }
+  async tableNotNullDrop(...args) {
+    await this._route(args[0]).tableNotNullDrop(...args);
+  }
+  async viewCreate(...args) {
+    await this._route(args[0]).viewCreate(...args);
+  }
+  async viewDrop(...args) {
+    await this._route(args[0]).viewDrop(...args);
+  }
+  async viewRename(...args) {
+    await this._route(args[0]).viewRename(...args);
+  }
+  async viewCommentSet(...args) {
+    await this._route(args[0]).viewCommentSet(...args);
+  }
+  async macroCreate(...args) {
+    await this._route(args[0]).macroCreate(...args);
+  }
+  async macroDrop(...args) {
+    await this._route(args[0]).macroDrop(...args);
+  }
+  async catalogContents(attachOpaqueData, ifNoneMatch) {
+    return await this._route(attachOpaqueData).catalogContents(attachOpaqueData, ifNoneMatch);
+  }
+  catalogContentsOwner(attachOpaqueData) {
+    return this._route(attachOpaqueData).catalogContentsOwner(attachOpaqueData);
+  }
   async copyFromFormats(attachOpaqueData, transactionOpaqueData) {
     return await this._route(attachOpaqueData).copyFromFormats(attachOpaqueData, transactionOpaqueData);
   }
@@ -10819,6 +11088,9 @@ function catalogUnary(protocol, signingKey, name, config) {
     result: config.result,
     doc: config.doc,
     handler: async (params, ctx) => {
+      if (params.request != null && params.attach_opaque_data === undefined && params.name === undefined) {
+        params = unwrapRequest(params.request);
+      }
       normalizeRequestSchemaPaths(params);
       await unwrapParamsOpaque(params, ctx, signingKey);
       return config.handler(params, ctx);
@@ -11672,6 +11944,134 @@ function hex(buf) {
   return Array.from(buf, (b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+// src/catalog/contents-digest.ts
+var KINDS = [
+  "tables",
+  "views",
+  "scalar_functions",
+  "aggregate_functions",
+  "table_functions",
+  "scalar_macros",
+  "table_macros",
+  "indexes"
+];
+async function catalogContentsDigest(schemas) {
+  const utf8 = new TextEncoder;
+  const parts = [];
+  let total = 0;
+  const count = (n) => {
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, BigInt(n), true);
+    parts.push(b);
+    total += 8;
+  };
+  const chunk = (data) => {
+    count(data.byteLength);
+    parts.push(data);
+    total += data.byteLength;
+  };
+  const chunks = (values) => {
+    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));
+  let hex = "";
+  for (const b of digest)
+    hex += b.toString(16).padStart(2, "0");
+  return hex;
+}
+
+// src/protocol/handlers/catalog/contents.ts
+var CACHE = new WeakMap;
+async function buildCatalogContents(cat, owner, attach, version, ifNoneMatch) {
+  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`);
+    }
+  }
+  const schemas = 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 });
+}
+async function serveCatalogContents(cat, attach, ifNoneMatch) {
+  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) {
+        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);
+}
+
 // src/protocol/handlers/catalog/admin.ts
 function registerCatalogAdminMethods(protocol, getCatalog, signingKey) {
   catalogUnary(protocol, signingKey, "catalog_catalogs", {
@@ -11699,25 +12099,11 @@ function registerCatalogAdminMethods(protocol, getCatalog, signingKey) {
       const optionsDict = decodeOptionsBatch(innerParams.options);
       const result = await cat.attach(innerParams.name, optionsDict, innerParams.data_version_spec ?? null, innerParams.implementation_version ?? null);
       const sealedAttach = await sealAttach(toUint8Array(result.attach_opaque_data), ctx?.auth, signingKey);
-      return wrapResult({
+      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 ?? {},
-        supports_column_statistics: result.supports_column_statistics ?? true,
-        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);
+        supports_column_statistics: result.supports_column_statistics ?? true
+      }), CatalogAttachResultSchema);
     }
   });
   catalogUnary(protocol, signingKey, "catalog_detach", {
@@ -11798,6 +12184,14 @@ function registerCatalogAdminMethods(protocol, getCatalog, signingKey) {
       }, CatalogSchemasResultSchema);
     }
   });
+  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);
+    }
+  });
   catalogUnary(protocol, signingKey, "catalog_copy_from_formats", {
     params: CatalogCopyFromFormatsParamsSchema,
     result: RESULT_BINARY_SCHEMA,
@@ -12092,7 +12486,7 @@ function registerCatalogMacroMethods(protocol, getCatalog, signingKey) {
     result: emptyResultSchema,
     handler: async (params) => {
       const cat = getCatalog();
-      const innerParams = unwrapRequest(params.request);
+      const innerParams = params;
       await cat.macroCreate(toUint8Array(innerParams.attach_opaque_data), innerParams.schema_path, innerParams.name, innerParams.macro_type, innerParams.parameters ? Array.isArray(innerParams.parameters) ? innerParams.parameters : [...innerParams.parameters] : [], innerParams.definition, innerParams.on_conflict, innerParams.parameter_default_values ? toUint8Array(innerParams.parameter_default_values) : null, innerParams.arguments_schema ? toUint8Array(innerParams.arguments_schema) : null, innerParams.transaction_opaque_data ? toUint8Array(innerParams.transaction_opaque_data) : undefined);
       return {};
     }
@@ -12158,7 +12552,7 @@ function registerCatalogMethods(protocol, catalog, _catalogName, signingKey) {
 // src/protocol/dispatch.ts
 var VGI_PROTOCOL_NAME = "vgi.v2";
 function buildVgiProtocol(config) {
-  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,
     signingKey: config.signingKey,
@@ -12798,7 +13192,118 @@ class VgiClient {
       global_functions: inner.global_functions ? (Array.isArray(inner.global_functions) ? inner.global_functions : [...inner.global_functions]).map(toUint8Array) : [],
       global_function_prefix: inner.global_function_prefix ?? "",
       resolved_data_version: inner.resolved_data_version ?? null,
-      resolved_implementation_version: inner.resolved_implementation_version ?? null
+      resolved_implementation_version: inner.resolved_implementation_version ?? null,
+      supports_catalog_contents: inner.supports_catalog_contents ?? false
+    };
+  }
+  async catalogContents(attachOpaqueData, ifNoneMatch = null) {
+    const result = await this.rpc.call("catalog_contents", {
+      attach_opaque_data: attachOpaqueData,
+      if_none_match: ifNoneMatch
+    });
+    if (!result)
+      throw new VgiClientError("catalog_contents returned null");
+    const response = decodeCatalogContentsResponse(toUint8Array(result.result));
+    const schemas = response.schemas.map((c) => {
+      const schema = decodeSchemaInfo(c.schema);
+      if (JSON.stringify(c.path) !== JSON.stringify(schema.path)) {
+        throw new VgiClientError(`catalog_contents: SchemaContents.path ${JSON.stringify(c.path)} != SchemaInfo.path ${JSON.stringify(schema.path)}`);
+      }
+      return {
+        schema,
+        tables: c.tables.map(decodeTableInfo),
+        views: c.views.map(decodeViewInfo),
+        scalar_functions: c.scalar_functions.map(decodeFunctionInfo),
+        aggregate_functions: c.aggregate_functions.map(decodeFunctionInfo),
+        table_functions: c.table_functions.map(decodeFunctionInfo),
+        scalar_macros: c.scalar_macros.map(decodeMacroInfo),
+        table_macros: c.table_macros.map(decodeMacroInfo),
+        indexes: c.indexes.map(decodeIndexInfo)
+      };
+    });
+    return {
+      catalog_version: Number(response.catalog_version ?? 0),
+      etag: response.etag ?? null,
+      not_modified: Boolean(response.not_modified),
+      schemas
+    };
+  }
+  async loadCatalog(attach, opts) {
+    const attachOpaqueData = attach.attach_opaque_data;
+    const previous = opts?.previous ?? null;
+    const useContents = attach.supports_catalog_contents === true && opts?.useCatalogContents !== false && opts?.transactionOpaqueData == null;
+    if (!useContents) {
+      return this._loadCatalogPerSchema(attachOpaqueData, opts?.transactionOpaqueData, null);
+    }
+    let fallbackError = null;
+    const ifNoneMatch = previous?.etag ?? null;
+    const knownVersion = previous?.catalog_version ?? 0;
+    for (let attempt = 0;attempt < 2; attempt++) {
+      let response;
+      try {
+        response = await this.catalogContents(attachOpaqueData, ifNoneMatch);
+      } catch (err) {
+        fallbackError = err instanceof Error ? err.message : String(err);
+        break;
+      }
+      if (response.not_modified) {
+        if (previous == null || ifNoneMatch == null) {
+          fallbackError = "catalog_contents answered not_modified to an unconditional request";
+          break;
+        }
+        return {
+          ...previous,
+          catalog_version: response.catalog_version !== 0 ? response.catalog_version : previous.catalog_version,
+          etag: response.etag ?? ifNoneMatch,
+          not_modified: true,
+          fallback_error: null
+        };
+      }
+      if (response.catalog_version !== 0 && knownVersion !== 0 && response.catalog_version < knownVersion) {
+        fallbackError = `catalog_contents snapshot version ${response.catalog_version} is older than the known version ${knownVersion}`;
+        continue;
+      }
+      return {
+        catalog_version: response.catalog_version,
+        etag: response.etag,
+        source: "catalog_contents",
+        not_modified: false,
+        fallback_error: null,
+        schemas: response.schemas
+      };
+    }
+    return this._loadCatalogPerSchema(attachOpaqueData, undefined, fallbackError);
+  }
+  async _loadCatalogPerSchema(attachOpaqueData, transactionOpaqueData, fallbackError) {
+    const schemas = await this.schemas(attachOpaqueData, transactionOpaqueData);
+    const out = [];
+    for (const schema of schemas) {
+      const counts = schema.estimated_object_count ?? {};
+      const path = schema.path;
+      const has = (kind) => {
+        const n = counts[kind];
+        return n == null || Number(n) !== 0;
+      };
+      const t = transactionOpaqueData;
+      out.push({
+        schema,
+        tables: has("table") ? await this.schemaContentsTables(attachOpaqueData, path, t) : [],
+        views: has("view") ? await this.schemaContentsViews(attachOpaqueData, path, t) : [],
+        scalar_functions: has("scalar_function") ? await this.schemaContentsFunctions(attachOpaqueData, path, "SCALAR_FUNCTION", t) : [],
+        aggregate_functions: has("aggregate_function") ? await this.schemaContentsFunctions(attachOpaqueData, path, "AGGREGATE_FUNCTION", t) : [],
+        table_functions: has("table_function") ? await this.schemaContentsFunctions(attachOpaqueData, path, "TABLE_FUNCTION", t) : [],
+        scalar_macros: has("macro") ? await this.schemaContentsMacros(attachOpaqueData, path, "SCALAR_MACRO", t) : [],
+        table_macros: has("macro") ? await this.schemaContentsMacros(attachOpaqueData, path, "TABLE_MACRO", t) : [],
+        indexes: has("index") ? await this.schemaContentsIndexes(attachOpaqueData, path, t) : []
+      });
+    }
+    return {
+      catalog_version: null,
+      etag: null,
+      source: "per_schema",
+      not_modified: false,
+      fallback_error: fallbackError,
+      schemas: out
     };
   }
   async catalogDetach(attachOpaqueData) {
@@ -12939,6 +13444,17 @@ class VgiClient {
     const inner = unwrapResult(result);
     return deserializeInfoList(inner.items, decodeFunctionInfo);
   }
+  async schemaContentsIndexes(attachOpaqueData, path, transactionOpaqueData) {
+    const result = await this.rpc.call("catalog_schema_contents_indexes", {
+      attach_opaque_data: attachOpaqueData,
+      path: normalizeSchemaPath(path),
+      transaction_opaque_data: transactionOpaqueData ?? null
+    });
+    if (!result)
+      return [];
+    const inner = unwrapResult(result);
+    return deserializeInfoList(inner.items, decodeIndexInfo);
+  }
   async tableGet(attachOpaqueData, schemaPath, name, transactionOpaqueData) {
     const result = await this.rpc.call("catalog_table_get", {
       attach_opaque_data: attachOpaqueData,
@@ -13203,9 +13719,103 @@ class VgiClient {
 // src/index.core.ts
 import { str, bytes, int as int3, int32 as int323, float, float32 as float323, bool as bool3, toSchema, OutputCollector, AuthContext } from "@query-farm/vgi-rpc";
 import { subprocessConnect, httpConnect, tcpConnect } from "@query-farm/vgi-rpc";
+
+// src/rpc-server.ts
+import {
+  IdentityImpl,
+  VgiRpcServer
+} from "@query-farm/vgi-rpc";
+var TRANSPORTS = new Set(["pipe", "unix", "tcp", "iroh", "stream", "http"]);
+var IDENTITY_TRANSPORTS = new Set(["http"]);
+var RESERVED_PREFIX = "vgi_rpc.";
+var INTROSPECT_PRINCIPALS_ENV = "VGI_INTROSPECT_PRINCIPALS";
+function buildRpcServer(primary, hosting, options) {
+  if (!TRANSPORTS.has(options.transport)) {
+    throw new Error(`Unknown transport ${JSON.stringify(options.transport)}; expected one of ${[...TRANSPORTS].join(", ")}.`);
+  }
+  const protocols = validatedHostedProtocols(hosting, primary);
+  const identity = IDENTITY_TRANSPORTS.has(options.transport) ? buildIdentity(hosting, options.env) : undefined;
+  return new VgiRpcServer(primary, {
+    serverId: options.serverId,
+    protocols,
+    identity
+  });
+}
+function validatedHostedProtocols(hosting, primary) {
+  if (hosting.hostedProtocols === undefined)
+    return [];
+  const owner = "hostedProtocols()";
+  if (typeof hosting.hostedProtocols !== "function") {
+    throw new TypeError(`${owner} must be a function returning vgi-rpc Protocols, got ${typeof hosting.hostedProtocols}.`);
+  }
+  const raw = hosting.hostedProtocols();
+  if (raw == null || typeof raw[Symbol.iterator] !== "function" || typeof raw === "string") {
+    throw new TypeError(`${owner} must return an iterable of vgi-rpc Protocols, got ${String(raw)}.`);
+  }
+  const seen = new Set;
+  const out = [];
+  let index = 0;
+  for (const proto of raw) {
+    const p = proto;
+    if (p == null || typeof p.name !== "string" || typeof p.getMethod !== "function") {
+      throw new TypeError(`${owner} entry ${index} must be a vgi-rpc Protocol, got ${String(proto)}.`);
+    }
+    const name = p.name;
+    if (name.startsWith(RESERVED_PREFIX)) {
+      throw new Error(`${owner} entry ${index} is named '${name}', which claims the reserved '${RESERVED_PREFIX}' prefix. ` + "Framework protocols are not supplied through this hook: reflection is hosted automatically, and " + "vgi_rpc.Identity.v1 is enabled by supplying resolveToken and/or mintGrant.");
+    }
+    if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(name)) {
+      throw new Error(`${owner} entry ${index}: protocol name '${name}' is not an identifier, optionally dot-qualified ` + "(e.g. 'acme.Reports.v1').");
+    }
+    if (name === primary.name) {
+      throw new Error(`${owner} entry ${index} is named '${name}', the worker's own protocol. Give it a distinct name.`);
+    }
+    if (seen.has(name)) {
+      throw new Error(`${owner} lists protocol name '${name}' twice. The name is the routing key, so each hosted protocol ` + "needs a distinct name.");
+    }
+    seen.add(name);
+    out.push(proto);
+    index++;
+  }
+  return out;
+}
+function buildIdentity(hosting, env) {
+  const { resolveToken, mintGrant } = hosting;
+  if (!resolveToken && !mintGrant)
+    return;
+  return new IdentityImpl({
+    resolveToken,
+    mintGrant,
+    introspectPrincipals: resolveToken ? resolveIntrospectPrincipals(hosting.introspectPrincipals, env) : undefined,
+    maxAuthAge: hosting.maxAuthAge
+  });
+}
+function resolveIntrospectPrincipals(explicit, env) {
+  let principals;
+  if (explicit !== undefined) {
+    principals = [...explicit].map((p) => p.trim()).filter((p) => p !== "");
+  } else {
+    const source = env ?? globalThis.process?.env;
+    const raw = source?.[INTROSPECT_PRINCIPALS_ENV] ?? "";
+    principals = raw.split(",").map((p) => p.trim()).filter((p) => p !== "");
+  }
+  if (principals.length === 0) {
+    throw new Error("This worker supplies resolveToken, which hosts the vgi_rpc.Identity.v1 protocol, but no " + `introspector allowlist was configured. Set ${INTROSPECT_PRINCIPALS_ENV} (comma-separated) or pass ` + `introspectPrincipals.
+
+` + "There is no permissive default on purpose: introspection is a separate capability from " + "authentication, and allowing every authenticated caller lets any user resolve any other user's " + "credential to its owner. Remove resolveToken to leave the protocol unhosted entirely.");
+  }
+  return principals;
+}
+
+// src/index.core.ts
+import {
+  AuthUnavailableError,
+  GrantRefusedError,
+  IdentityUnavailableError,
+  StatusError
+} from "@query-farm/vgi-rpc";
 // src/worker.ts
 import {
-  VgiRpcServer,
   observePeerIdentity,
   peerIdentityPrimary,
   serveUnix,
@@ -13269,11 +13879,19 @@ function parseLauncherArgs(argv) {
 
 class Worker {
   _registry;
+  _hosting;
   _catalogInterface;
   _catalogName;
   constructor(config) {
     this._registry = config.registry ?? new FunctionRegistry;
     this._catalogName = config.catalogName;
+    this._hosting = {
+      hostedProtocols: config.hostedProtocols,
+      resolveToken: config.resolveToken,
+      mintGrant: config.mintGrant,
+      introspectPrincipals: config.introspectPrincipals,
+      maxAuthAge: config.maxAuthAge
+    };
     if (config.functions) {
       for (const func of config.functions) {
         this._registry.register(func);
@@ -13313,7 +13931,7 @@ class Worker {
         const envOverride = process.env.VGI_WORKER_IDLE_TIMEOUT;
         const idleTimeout = envOverride !== undefined && envOverride !== "" ? Number(envOverride) : launcher.idleTimeout;
         debug(() => `[worker] AF_UNIX mode: ${launcher.unixPath} idle=${idleTimeout ?? 300}s${envOverride !== undefined && envOverride !== "" ? " (env override)" : ""}`);
-        serveUnix(protocol, {
+        serveUnix(this.buildServer(protocol, "unix"), {
           unixPath: launcher.unixPath,
           idleTimeout
         }).then((handle) => handle.done).then(() => {
@@ -13330,7 +13948,7 @@ ${err.stack}
         const envOverride = process.env.VGI_WORKER_IDLE_TIMEOUT;
         const idleTimeout = envOverride !== undefined && envOverride !== "" ? Number(envOverride) : launcher.idleTimeout;
         debug(() => `[worker] TCP mode: ${launcher.tcpHost}:${launcher.tcpPort} idle=${idleTimeout ?? 300}s${envOverride !== undefined && envOverride !== "" ? " (env override)" : ""}`);
-        serveTcp(protocol, {
+        serveTcp(this.buildServer(protocol, launcher.irohRawUpstream ? "iroh" : "tcp"), {
           host: launcher.tcpHost,
           port: launcher.tcpPort,
           idleTimeout,
@@ -13350,7 +13968,7 @@ ${err.stack}
         });
         return;
       }
-      const server = new VgiRpcServer(protocol);
+      const server = this.buildServer(protocol, "pipe");
       debug(() => `[worker] server created, calling run()`);
       server.run().then(() => {
         debug(() => `[worker] server.run() resolved cleanly`);
@@ -13367,6 +13985,9 @@ ${err.stack}
       process.exit(1);
     }
   }
+  buildServer(protocol, transport) {
+    return buildRpcServer(protocol, this._hosting, { transport });
+  }
   buildProtocol() {
     return buildVgiProtocol({
       registry: this._registry,
@@ -13375,7 +13996,7 @@ ${err.stack}
     });
   }
   async serveStream(readable, writable) {
-    await serveStreamRpc(this.buildProtocol(), { readable, writable });
+    await serveStreamRpc(this.buildServer(this.buildProtocol(), "stream"), { readable, writable });
   }
 }
 export {
@@ -13383,6 +14004,7 @@ export {
   ArgumentValidationError,
   Arguments,
   AuthContext,
+  AuthUnavailableError,
   BindResultSchema,
   BoundStorage,
   CACHE_ETAG_KEY,
@@ -13420,6 +14042,9 @@ export {
   FunctionStorageSqlite,
   FunctionType,
   GROUP_COLUMN_NAME,
+  GrantRefusedError,
+  INTROSPECT_PRINCIPALS_ENV,
+  IdentityUnavailableError,
   IntervalUnit2 as IntervalUnit,
   NoCatalogError,
   NullHandling,
@@ -13428,9 +14053,11 @@ export {
   OutputCollector,
   PARENT_ROW_METADATA_KEY,
   PushdownFilters,
+  READ_ONLY_ITEM_ATTACH_ID,
   ReadOnlyCatalogInterface,
   RowCountMismatchError,
   ScanFunctionResultSchema,
+  StatusError,
   TableInOutPhase,
   TimeUnit2 as TimeUnit,
   TypeId,
@@ -13468,7 +14095,9 @@ export {
   batchToSecretDict,
   binary2 as binary,
   bool3 as bool,
+  buildCatalogAttachResult,
   buildJoinKeysLookup,
+  buildRpcServer,
   buildScanBranchesResult,
   buildVgiProtocol,
   bytes,
@@ -13621,4 +14250,4 @@ export {
   utf82 as utf8
 };
 
-//# debugId=2D7783DC9EE1AD4F64756E2164756E21
+//# debugId=03676B1C4ED9A21664756E2164756E21