@query-farm/vgi 0.37.1 → 0.39.0

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";
 
@@ -303,10 +303,31 @@ export type {
   CatalogFunctionType as ClientCatalogFunctionType,
   CatalogAttachOptions,
   AttachOptionValue,
+  CatalogSnapshot,
+  LoadCatalogOptions,
 } from "./client/types.js";
 
 // Re-export from vgi-rpc for convenience
 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,
+  );
+}

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

@@ -52,7 +52,8 @@ export function registerCatalogMacroMethods(protocol: Protocol, getCatalog: GetC
     result: emptyResultSchema,
     handler: async (params) => {
       const cat = getCatalog();
-      const innerParams = unwrapRequest(params.request);
+      // catalogUnary already flattened the wrapped request.
+      const innerParams = params;
       await cat.macroCreate(
         toUint8Array(innerParams.attach_opaque_data),
         innerParams.schema_path,

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

@@ -7,7 +7,7 @@ import type { CatalogInterface } from "../../../catalog/interface.js";
 import { NoCatalogError } from "../../../errors.js";
 import { deserializeBatch } from "../../../util/arrow/index.js";
 import { toUint8Array } from "../../../util/bytes.js";
-import { normalizeRequestSchemaPaths } from "../shared.js";
+import { normalizeRequestSchemaPaths, unwrapRequest } from "../shared.js";
 import {
   sealBytes,
   openBytes,
@@ -195,6 +195,17 @@ export function catalogUnary(
     result: config.result as any,
     doc: config.doc,
     handler: async (params: Record<string, any>, ctx: any) => {
+      // catalog_create / catalog_table_create / catalog_macro_create (and
+      // catalog_index_create) send one `request: binary` column holding the
+      // IPC-serialized request record, so their attach/transaction values ride
+      // INSIDE it. Flatten it first, so handlers read the request's fields
+      // directly and those values are opened (and the framework UUID stripped)
+      // like every other catalog call's. Before this, table_create read every
+      // field off the envelope (all undefined) and macro_create handed the
+      // catalog an unopened attach value.
+      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);