@query-farm/vgi 0.14.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.14.0",
+  "version": "0.17.0",
   "description": "TypeScript framework for extending DuckDB with user-defined functions via the Vector Gateway Interface (VGI) over Arrow IPC.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Query Farm LLC (https://query.farm)",
@@ -29,7 +29,13 @@
     "node": ">=22.15"
   },
   "type": "module",
-  "sideEffects": false,
+  "//sideEffects": "Entry modules are listed so the bundler cannot tree-shake them away. Under a bare `sideEffects: false`, an entry consisting only of re-exports builds to a dangling export list with no imports and no definitions \u2014 invalid ESM that throws on first import. Modules not listed stay side-effect-free, so consumers still tree-shake normally.",
+  "sideEffects": [
+    "./src/index.ts",
+    "./src/client-entry.ts",
+    "./src/worker-cf-entry.ts",
+    "./src/serve-entry.ts"
+  ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -53,6 +59,11 @@
       "browser": "./src/worker-cf-entry.ts",
       "bun": "./src/worker-cf-entry.ts",
       "import": "./dist/worker-cf-entry.js"
+    },
+    "./serve": {
+      "types": "./dist/serve-entry.d.ts",
+      "bun": "./src/serve-entry.ts",
+      "import": "./dist/serve-entry.js"
     }
   },
   "files": [
@@ -75,20 +86,21 @@
   },
   "peerDependencies": {
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": "^0.11.0"
+    "@query-farm/vgi-rpc": "^0.13.0"
   },
   "devDependencies": {
     "@duckdb/node-api": "^1.5.2-r.1",
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": "^0.11.0",
+    "@query-farm/vgi-rpc": "^0.13.0",
     "@types/bun": "latest",
     "typescript": "^6.0.3"
   },
   "scripts": {
-    "build": "bun run build:types && bun run build:js",
+    "build": "bun run build:types && bun run build:js && bun run check:bundles",
+    "check:bundles": "bun run scripts/check-bundles.ts",
     "prepack": "bun run build",
     "build:types": "bunx tsc -p tsconfig.build.json",
-    "build:js": "bun build ./src/index.ts --outdir dist --target node --format esm --sourcemap=external --external @query-farm/apache-arrow --external @query-farm/vgi-rpc && bun build ./src/client-entry.ts --outdir dist --target browser --format esm --sourcemap=external --external @query-farm/apache-arrow --external @query-farm/vgi-rpc && bun build ./src/worker-cf-entry.ts --outdir dist --target node --format esm --sourcemap=external --external @query-farm/apache-arrow --external @query-farm/vgi-rpc",
+    "build:js": "bun build ./src/index.ts --outdir dist --target node --format esm --sourcemap=external --external @query-farm/apache-arrow --external @query-farm/vgi-rpc && bun build ./src/client-entry.ts --outdir dist --target browser --format esm --sourcemap=external --external @query-farm/apache-arrow --external @query-farm/vgi-rpc && bun build ./src/worker-cf-entry.ts --outdir dist --target node --format esm --sourcemap=external --external @query-farm/apache-arrow --external @query-farm/vgi-rpc && bun build ./src/serve-entry.ts --outdir dist --target bun --format esm --sourcemap=external --external @query-farm/apache-arrow --external @query-farm/vgi-rpc",
     "postinstall": "node scripts/postinstall.cjs",
     "build:browser-test": "bun build examples/browser/main.ts --outdir examples/browser/dist --target browser --format esm --sourcemap=external",
     "test": "bun test"

package/src/cache-control.ts

@@ -0,0 +1,133 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+/**
+ * Result-cache control metadata (`vgi.cache.*`).
+ *
+ * A table function can advertise that its result is cacheable by the client
+ * (the DuckDB extension) by attaching `vgi.cache.*` metadata to the **first**
+ * data batch it emits. The vocabulary mirrors HTTP caching (RFC 9111/9110): a
+ * freshness lifetime (`ttl` / `expires`), a reuse `scope`, validators
+ * (ETag / Last-Modified) for conditional revalidation, and stale-serving grace
+ * windows.
+ *
+ * The key strings are the single source of truth shared with the C++ extension
+ * (which reads them by string). {@link cacheControlMetadata} renders a
+ * {@link CacheControl} to the `Map<string, string>` of `vgi.cache.*` keys that
+ * rides on batch metadata:
+ *
+ * ```ts
+ * out.emit(firstBatch, cacheControlMetadata({ ttl: 300 }));
+ * ```
+ *
+ * Pass `extra` to merge in metadata a function already emits per batch (for
+ * example `vgi_batch_index`); the rendered cache keys win on collision.
+ *
+ * Booleans render as `"1"` and are omitted when false; timestamps are RFC 3339
+ * UTC strings; durations are whole seconds.
+ *
+ * Ports `vgi/cache_control.py` from vgi-python.
+ */
+
+// --- Response-side metadata keys (worker -> client) -------------------------
+// Defined once here; the C++ extension reads these exact strings.
+
+export const CACHE_TTL_KEY = "vgi.cache.ttl";
+export const CACHE_EXPIRES_KEY = "vgi.cache.expires";
+export const CACHE_NO_STORE_KEY = "vgi.cache.no_store";
+export const CACHE_SCOPE_KEY = "vgi.cache.scope";
+export const CACHE_ETAG_KEY = "vgi.cache.etag";
+export const CACHE_LAST_MODIFIED_KEY = "vgi.cache.last_modified";
+export const CACHE_REVALIDATABLE_KEY = "vgi.cache.revalidatable";
+export const CACHE_STALE_WHILE_REVALIDATE_KEY = "vgi.cache.stale_while_revalidate";
+export const CACHE_STALE_IF_ERROR_KEY = "vgi.cache.stale_if_error";
+export const CACHE_NOT_MODIFIED_KEY = "vgi.cache.not_modified";
+
+// --- Request-side metadata keys (client -> worker) --------------------------
+// Ride on the first producer tick; surfaced as `TableProcessParams.ifNoneMatch`
+// / `.ifModifiedSince`.
+
+export const CACHE_IF_NONE_MATCH_KEY = "vgi.cache.if_none_match";
+export const CACHE_IF_MODIFIED_SINCE_KEY = "vgi.cache.if_modified_since";
+
+// --- Reuse-scope values -----------------------------------------------------
+
+export const CACHE_SCOPE_CATALOG = "catalog";
+export const CACHE_SCOPE_TRANSACTION = "transaction";
+
+/** Reuse scope for a cacheable result. */
+export type CacheScope = typeof CACHE_SCOPE_CATALOG | typeof CACHE_SCOPE_TRANSACTION;
+
+/**
+ * Cacheability advertised by a table function on its first result batch.
+ *
+ * Presence of `ttl` **or** `expires` is what makes a result cacheable;
+ * `noStore` overrides any freshness key.
+ */
+export interface CacheControl {
+  /** Freshness lifetime in whole seconds, relative to full-result receipt
+   *  (skew-immune; wins over `expires`). */
+  ttl?: number;
+  /** Absolute RFC 3339 UTC deadline. Lifetime is `expires - now` at receipt. */
+  expires?: string;
+  /** Reuse scope — `"catalog"` (default; reusable across transactions within
+   *  the calling catalog identity) or `"transaction"` (reused only within the
+   *  same transaction). */
+  scope?: CacheScope;
+  /** Explicit "never cache"; overrides any freshness key. */
+  noStore?: boolean;
+  /** Strong validator (opaque quoted string) for conditional revalidation. */
+  etag?: string;
+  /** Weaker RFC 3339 UTC validator; fallback when no ETag. */
+  lastModified?: string;
+  /** The worker can check freshness cheaply without recomputing; gates whether
+   *  the client ever sends a conditional request. */
+  revalidatable?: boolean;
+  /** Grace window (seconds) to serve stale immediately while revalidating in
+   *  the background. */
+  staleWhileRevalidate?: number;
+  /** Grace window (seconds) to serve stale if a revalidation RPC fails. */
+  staleIfError?: number;
+  /** 304-equivalent — set on a 0-row batch in reply to a conditional request to
+   *  assert the client's stored payload is still fresh (the client reuses it
+   *  instead of re-streaming). */
+  notModified?: boolean;
+}
+
+const VALID_SCOPES: readonly string[] = [CACHE_SCOPE_CATALOG, CACHE_SCOPE_TRANSACTION];
+
+/**
+ * Render a {@link CacheControl} to the `vgi.cache.*` batch-metadata map.
+ *
+ * `scope` is always emitted so the client never has to infer the default.
+ * Unset optional fields are omitted; false booleans are omitted. Entries from
+ * `extra` are written first, so a rendered cache key wins on collision.
+ *
+ * Throws when `scope` is unrecognized or a duration is negative — a silently
+ * ignored advertisement is far harder to debug than a stack trace at the
+ * offending `emit()`.
+ */
+export function cacheControlMetadata(cc: CacheControl, extra?: Map<string, string>): Map<string, string> {
+  const scope = cc.scope ?? CACHE_SCOPE_CATALOG;
+  if (!VALID_SCOPES.includes(scope)) {
+    throw new Error(`CacheControl.scope must be one of ${VALID_SCOPES.join(", ")}, got ${JSON.stringify(scope)}`);
+  }
+  for (const name of ["ttl", "staleWhileRevalidate", "staleIfError"] as const) {
+    const value = cc[name];
+    if (value !== undefined && value < 0) {
+      throw new Error(`CacheControl.${name} must be >= 0, got ${value}`);
+    }
+  }
+
+  const md = new Map<string, string>(extra ?? []);
+  if (cc.ttl !== undefined) md.set(CACHE_TTL_KEY, String(cc.ttl));
+  if (cc.expires !== undefined) md.set(CACHE_EXPIRES_KEY, cc.expires);
+  if (cc.noStore) md.set(CACHE_NO_STORE_KEY, "1");
+  md.set(CACHE_SCOPE_KEY, scope);
+  if (cc.etag !== undefined) md.set(CACHE_ETAG_KEY, cc.etag);
+  if (cc.lastModified !== undefined) md.set(CACHE_LAST_MODIFIED_KEY, cc.lastModified);
+  if (cc.revalidatable) md.set(CACHE_REVALIDATABLE_KEY, "1");
+  if (cc.staleWhileRevalidate !== undefined) md.set(CACHE_STALE_WHILE_REVALIDATE_KEY, String(cc.staleWhileRevalidate));
+  if (cc.staleIfError !== undefined) md.set(CACHE_STALE_IF_ERROR_KEY, String(cc.staleIfError));
+  if (cc.notModified) md.set(CACHE_NOT_MODIFIED_KEY, "1");
+  return md;
+}

package/src/functions/table.ts

@@ -51,6 +51,7 @@ import {
   type DistinctDependence,
 } from "../types.js";
 import { BoundStorage, storage as globalStorage } from "./storage.js";
+import { CACHE_IF_MODIFIED_SINCE_KEY, CACHE_IF_NONE_MATCH_KEY } from "../cache-control.js";
 
 // Base64-decode a string into raw bytes. Used to unpack the dynamic filter
 // update DuckDB attaches to each tick batch's custom metadata.
@@ -153,6 +154,18 @@ export interface TableProcessParams<TArgs = Record<string, any>> {
    */
   atUnit?: string;
   atValue?: string;
+  /**
+   * Conditional-revalidation validator (the client's stored ETag). Set when the
+   * client holds a stale-but-revalidatable cached result and asks the worker to
+   * confirm freshness cheaply; a worker that advertised `revalidatable` compares
+   * it and, if unchanged, emits a 0-row batch tagged
+   * `cacheControlMetadata({ notModified: true })` instead of re-streaming.
+   * Undefined on a normal call.
+   */
+  ifNoneMatch?: string;
+  /** Conditional-revalidation validator (the client's stored Last-Modified).
+   *  Companion to {@link ifNoneMatch}. Undefined on a normal call. */
+  ifModifiedSince?: string;
 }
 
 // ============================================================================
@@ -443,12 +456,23 @@ export function defineTableFunction<
           pState: { state: TState; processParams: TableProcessParams<TArgs> },
           tickMetadata: Map<string, string> | undefined,
         ) => {
+          if (!tickMetadata) return;
+
+          // Conditional-revalidation validators: the client holds a stale
+          // cached result and asks the worker to confirm freshness cheaply.
+          // Over subprocess these ride the first producer tick; over HTTP the
+          // first tick folds into the /init request, whose metadata vgi-rpc
+          // surfaces here.
+          const ifNoneMatch = tickMetadata.get(CACHE_IF_NONE_MATCH_KEY);
+          const ifModifiedSince = tickMetadata.get(CACHE_IF_MODIFIED_SINCE_KEY);
+          if (ifNoneMatch !== undefined) pState.processParams.ifNoneMatch = ifNoneMatch;
+          if (ifModifiedSince !== undefined) pState.processParams.ifModifiedSince = ifModifiedSince;
+
           // Dynamic filter pushdown: DuckDB's Top-N optimizer tightens filters
           // between ticks and serializes the current filter into the tick
           // batch's custom metadata under `vgi_pushdown_filters` (base64 of a
           // filter IPC stream). Decode and overwrite the current pushdown
           // filters so process() sees the updated value.
-          if (!tickMetadata) return;
           const encoded = tickMetadata.get("vgi_pushdown_filters");
           if (!encoded) return;
           try {

package/src/http/describe-json.ts

@@ -399,7 +399,12 @@ async function buildSchemas(
         String(a.type).localeCompare(String(b.type)) || String(a.name).localeCompare(String(b.name)),
     );
 
-    schemas.push({ name: si.name, tables, views, functions });
+    const schemaObj: Record<string, unknown> = { name: si.name };
+    if (si.comment) schemaObj.doc = si.comment;
+    schemaObj.tables = tables;
+    schemaObj.views = views;
+    schemaObj.functions = functions;
+    schemas.push(schemaObj);
     counts.schemas += 1;
     counts.tables += tables.length;
     counts.views += views.length;

package/src/http/fetch.ts

@@ -0,0 +1,80 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// Shared HTTP fetch-handler factory for VGI workers.
+//
+// Both HTTP entrypoints funnel through here:
+//   - `vgi/worker-cf`  -> createVgiFetch, exported as `default.fetch` for workerd
+//   - `vgi/serve`      -> serveVgiWorker, which hands the handler to Bun.serve
+//
+// Centralising the wiring means the state-token key reaches `createHttpHandler`
+// as `tokenKey` (the option the handler actually reads) and reaches
+// `buildVgiProtocol` as `signingKey`, from one source. Passing different keys to
+// those two seams produces a worker that mints tokens it cannot recover.
+
+import { createHttpHandler, unpackStateToken, type Protocol } from "@query-farm/vgi-rpc";
+import { arrowStateSerializer } from "../protocol/state-serializer.js";
+import { buildVgiProtocol, type ProtocolConfig } from "../protocol/dispatch.js";
+import type { LandingDescribeProvider } from "./describe-json.js";
+
+export interface VgiFetchOptions {
+  /** Wire-protocol config (registry + catalogInterface). */
+  protocol: Omit<ProtocolConfig, "recoverExchangeState">;
+  /** HMAC key for state-token signing. Pass a stable, secret 32-byte key
+   *  (e.g. derived from a Wrangler secret). Required because Workers don't
+   *  preserve in-memory state across requests/instances. */
+  signingKey: Uint8Array;
+  /** State-token TTL in seconds (default 3600). */
+  tokenTtl?: number;
+  /** URL path prefix for VGI requests (default "/vgi"). Pass "" to mount at
+   *  the root, which is what a dedicated single-worker HTTP server wants. */
+  prefix?: string;
+  /** Server ID for state-token attribution (default "vgi-cf"). */
+  serverId?: string;
+  /** CORS allowed origins. When set, CORS headers are added to all responses,
+   *  and the preflight `OPTIONS` that browser clients (e.g. the hosted Cupola
+   *  UI) send before `__describe__` will succeed. Omit to disable CORS. */
+  corsOrigins?: string;
+  /** Public source-repository URL, surfaced on the landing page. */
+  repositoryUrl?: string;
+  /** Enables the standardized VGI landing surface: `GET /` serves the shared
+   *  landing.html, `GET /describe.json` the catalog contract, and
+   *  `GET /describe/{catalog}/{schema}/{table}.json` lazy per-object columns.
+   *  Build one with `createLandingDescribe(catalogInterface, workerInfo)`. */
+  landingDescribe?: LandingDescribeProvider;
+}
+
+/**
+ * Build a fetch handler suitable for `export default { fetch }` in a CF
+ * Worker module, or for `Bun.serve({ fetch })`. The returned handler is
+ * async-safe across Workers' isolate-per-request execution model — all state
+ * round-trips through the signed state token created here.
+ */
+export function createVgiFetch(opts: VgiFetchOptions): (req: Request) => Promise<Response> {
+  const tokenTtl = opts.tokenTtl ?? 3600;
+  // `?? "/vgi"` and not `|| "/vgi"`: an explicit "" means "mount at root".
+  const prefix = opts.prefix ?? "/vgi";
+  const serverId = opts.serverId ?? "vgi-cf";
+
+  const protocol: Protocol = buildVgiProtocol({
+    signingKey: opts.signingKey,
+    ...opts.protocol,
+    recoverExchangeState: async (opaqueData: Uint8Array) => {
+      const tokenString = new TextDecoder().decode(opaqueData);
+      // principal binding is enforced by the HTTP handler on the request that
+      // carried this token; the recovery path itself is not principal-scoped.
+      const unpacked = await unpackStateToken(tokenString, opts.signingKey, tokenTtl, undefined);
+      return arrowStateSerializer.deserialize(unpacked.stateBytes);
+    },
+  });
+
+  const handler = createHttpHandler(protocol, {
+    prefix,
+    serverId,
+    tokenKey: opts.signingKey,
+    tokenTtl,
+    stateSerializer: arrowStateSerializer,
+    corsOrigins: opts.corsOrigins,
+    repositoryUrl: opts.repositoryUrl,
+    landingDescribe: opts.landingDescribe,
+  });
+  return async (req: Request) => handler(req);
+}

package/src/index.core.ts

@@ -7,6 +7,27 @@
 // for Cloudflare Workers / browsers via worker-cf-entry.ts. The node/bun barrel
 // (`./index.ts`) re-exports this plus `Worker`.
 
+// Result-cache control vocabulary (`vgi.cache.*`)
+export {
+  CACHE_ETAG_KEY,
+  CACHE_EXPIRES_KEY,
+  CACHE_IF_MODIFIED_SINCE_KEY,
+  CACHE_IF_NONE_MATCH_KEY,
+  CACHE_LAST_MODIFIED_KEY,
+  CACHE_NO_STORE_KEY,
+  CACHE_NOT_MODIFIED_KEY,
+  CACHE_REVALIDATABLE_KEY,
+  CACHE_SCOPE_CATALOG,
+  CACHE_SCOPE_KEY,
+  CACHE_SCOPE_TRANSACTION,
+  CACHE_STALE_IF_ERROR_KEY,
+  CACHE_STALE_WHILE_REVALIDATE_KEY,
+  CACHE_TTL_KEY,
+  type CacheControl,
+  cacheControlMetadata,
+  type CacheScope,
+} from "./cache-control.js";
+
 // Function factories (primary API)
 export { defineScalarFunction, type ScalarFunctionConfig, type ScalarBindParameters, type ScalarParameterDef } from "./functions/scalar.js";
 export { defineTableFunction, type TableFunctionConfig, type TableBindParams, type TableProcessParams } from "./functions/table.js";

package/src/serve-entry.ts

@@ -0,0 +1,233 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// Bun HTTP entrypoint for a VGI worker: `import { serveVgiWorker } from "@query-farm/vgi/serve"`.
+//
+// A worker's HTTP server is the same nine moving parts every time (protocol,
+// state-token key, TTL, CORS, landing surface, port, Bun.serve, startup log).
+// This collapses them to one call so a worker repo's serve script is its
+// registry + catalog and nothing else:
+//
+//   serveVgiWorker({
+//     name: "ishares",
+//     doc: "iShares (BlackRock) US fund data.",
+//     version: "0.1.0",
+//     repositoryUrl: "https://github.com/Query-farm/vgi-etf-ishares",
+//     registry,
+//     catalogInterface,
+//   });
+//
+// Mounted at the ROOT prefix, so DuckDB attaches the bare origin:
+//   ATTACH 'ishares' AS ishares (TYPE vgi, LOCATION 'http://localhost:8787');
+//
+// Bun-only — it calls Bun.serve. Cloudflare Workers use `vgi/worker-cf`'s
+// createVgiFetch instead; both share the handler factory in http/fetch.ts.
+
+import type { CatalogInterface } from "./catalog/interface.js";
+import type { FunctionRegistry } from "./functions/registry.js";
+import { createLandingDescribe } from "./http/describe-json.js";
+import { createVgiFetch } from "./http/fetch.js";
+
+/** Environment variables `serveVgiWorker` reads. Injectable for testing. */
+export interface ServeEnv {
+  PORT?: string;
+  VGI_SIGNING_KEY?: string;
+  VGI_TOKEN_TTL?: string;
+  CORS_ORIGINS?: string;
+}
+
+export const DEFAULT_PORT = 8787;
+export const DEFAULT_TOKEN_TTL = 3600;
+/** Bytes of HMAC key `createHttpHandler` expects; 64 hex characters. */
+export const SIGNING_KEY_BYTES = 32;
+
+export interface ServeVgiWorkerOptions {
+  /** Short worker name shown on the landing page, e.g. "ishares". */
+  name: string;
+  /** One-line description of what the worker serves. */
+  doc: string;
+  /** Worker version string shown on the landing page. */
+  version: string;
+  /** Functions the worker serves, already registered. */
+  registry: FunctionRegistry;
+  /** Catalog DuckDB attaches to. */
+  catalogInterface: CatalogInterface;
+
+  /** Public source-repository URL, linked from the landing page. */
+  repositoryUrl?: string;
+  /** Overrides `$PORT` (default 8787). Pass 0 to bind an ephemeral port. */
+  port?: number;
+  /** Overrides `$VGI_SIGNING_KEY`. 32 bytes. */
+  signingKey?: Uint8Array;
+  /** Overrides `$VGI_TOKEN_TTL` (default 3600 seconds). */
+  tokenTtl?: number;
+  /** Overrides `$CORS_ORIGINS` (default "*"). Pass `null` to disable CORS. */
+  corsOrigins?: string | null;
+  /** Server ID for state-token attribution (default: `name`). */
+  serverId?: string;
+  /** Mount point for the VGI endpoints (default "", the origin root). */
+  prefix?: string;
+  /** Suppress the startup banner on stdout. */
+  quiet?: boolean;
+  /** Environment source (default `process.env`). */
+  env?: ServeEnv;
+}
+
+/** The slice of `Bun.serve`'s return value this module uses. */
+export interface VgiHttpServer {
+  readonly port: number;
+  readonly url: URL;
+  stop(closeActiveConnections?: boolean): void;
+}
+
+interface BunLike {
+  serve(options: {
+    port: number;
+    fetch: (req: Request) => Promise<Response>;
+  }): VgiHttpServer;
+}
+
+/**
+ * Decode a 32-byte signing key from its hex representation.
+ *
+ * Throws on anything that is not exactly 64 hex characters. A silent truncate
+ * or zero-pad here would produce a worker that starts happily with a key far
+ * weaker than the operator believed they supplied.
+ */
+export function parseSigningKeyHex(hex: string): Uint8Array {
+  const cleaned = hex.trim();
+  const expected = SIGNING_KEY_BYTES * 2;
+  if (cleaned.length !== expected || !/^[0-9a-fA-F]+$/.test(cleaned)) {
+    throw new Error(
+      `VGI_SIGNING_KEY must be exactly ${expected} hex characters ` +
+        `(${SIGNING_KEY_BYTES} bytes); got ${cleaned.length}. ` +
+        `Generate one with: openssl rand -hex ${SIGNING_KEY_BYTES}`,
+    );
+  }
+  const key = new Uint8Array(SIGNING_KEY_BYTES);
+  for (let i = 0; i < SIGNING_KEY_BYTES; i++) {
+    key[i] = Number.parseInt(cleaned.slice(i * 2, i * 2 + 2), 16);
+  }
+  return key;
+}
+
+/**
+ * Resolve the state-token signing key: explicit option, then `$VGI_SIGNING_KEY`,
+ * then a fresh random key.
+ *
+ * The random fallback is safe but ephemeral, and that tradeoff is why it warns:
+ * state tokens minted under it stop validating after a restart, and never
+ * validate across a second instance behind a load balancer. It exists so
+ * `bun run scripts/serve.ts` works with no setup, not so deployments can skip
+ * the key.
+ */
+export function resolveSigningKey(
+  explicit: Uint8Array | undefined,
+  env: ServeEnv,
+  warn: (msg: string) => void = console.error,
+): Uint8Array {
+  if (explicit) {
+    if (explicit.length !== SIGNING_KEY_BYTES) {
+      throw new Error(
+        `signingKey must be ${SIGNING_KEY_BYTES} bytes; got ${explicit.length}.`,
+      );
+    }
+    return explicit;
+  }
+  const fromEnv = env.VGI_SIGNING_KEY?.trim();
+  if (fromEnv) return parseSigningKeyHex(fromEnv);
+
+  warn(
+    "WARNING: VGI_SIGNING_KEY is not set; generated a random state-token key.\n" +
+      "         State tokens will not survive a restart, and will not validate\n" +
+      "         across multiple instances behind a load balancer.\n" +
+      `         Set it for any real deployment: openssl rand -hex ${SIGNING_KEY_BYTES}`,
+  );
+  return crypto.getRandomValues(new Uint8Array(SIGNING_KEY_BYTES));
+}
+
+function resolvePort(explicit: number | undefined, env: ServeEnv): number {
+  if (explicit !== undefined) return explicit;
+  const raw = env.PORT?.trim();
+  if (!raw) return DEFAULT_PORT;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error(`PORT must be an integer between 0 and 65535; got ${JSON.stringify(raw)}.`);
+  }
+  return port;
+}
+
+function resolveTokenTtl(explicit: number | undefined, env: ServeEnv): number {
+  if (explicit !== undefined) return explicit;
+  const raw = env.VGI_TOKEN_TTL?.trim();
+  if (!raw) return DEFAULT_TOKEN_TTL;
+  const ttl = Number(raw);
+  if (!Number.isInteger(ttl) || ttl < 0) {
+    throw new Error(`VGI_TOKEN_TTL must be a non-negative integer; got ${JSON.stringify(raw)}.`);
+  }
+  return ttl;
+}
+
+/**
+ * Build the fetch handler a VGI worker serves over HTTP, with the standardized
+ * landing surface mounted at `prefix`.
+ *
+ * Exposed separately from {@link serveVgiWorker} so a worker can put the VGI
+ * routes inside its own Bun/Hono/Elysia server, or drive them from a test
+ * without binding a port.
+ */
+export function createVgiWorkerFetch(
+  opts: ServeVgiWorkerOptions,
+): (req: Request) => Promise<Response> {
+  const env = opts.env ?? (process.env as ServeEnv);
+  const signingKey = resolveSigningKey(opts.signingKey, env);
+  const tokenTtl = resolveTokenTtl(opts.tokenTtl, env);
+  // `null` disables CORS; `undefined` falls through to the env var, then "*".
+  const corsOrigins =
+    opts.corsOrigins === null ? undefined : (opts.corsOrigins ?? env.CORS_ORIGINS ?? "*");
+
+  return createVgiFetch({
+    protocol: { registry: opts.registry, catalogInterface: opts.catalogInterface },
+    signingKey,
+    tokenTtl,
+    prefix: opts.prefix ?? "",
+    serverId: opts.serverId ?? opts.name,
+    corsOrigins,
+    repositoryUrl: opts.repositoryUrl,
+    landingDescribe: createLandingDescribe(opts.catalogInterface, {
+      name: opts.name,
+      doc: opts.doc,
+      version: opts.version,
+    }),
+  });
+}
+
+/**
+ * Serve a VGI worker over HTTP on Bun and return the running server.
+ *
+ * Reads `PORT`, `VGI_SIGNING_KEY`, `VGI_TOKEN_TTL`, and `CORS_ORIGINS` from the
+ * environment; every one has an explicit option that takes precedence.
+ */
+export function serveVgiWorker(opts: ServeVgiWorkerOptions): VgiHttpServer {
+  const runtime = (globalThis as { Bun?: BunLike }).Bun;
+  if (!runtime) {
+    throw new Error(
+      '"@query-farm/vgi/serve" requires the Bun runtime (it calls Bun.serve). ' +
+        'On Cloudflare Workers use createVgiFetch from "@query-farm/vgi/worker-cf"; ' +
+        "on other runtimes use createVgiWorkerFetch and bind the port yourself.",
+    );
+  }
+
+  const env = opts.env ?? (process.env as ServeEnv);
+  const port = resolvePort(opts.port, env);
+  const fetch = createVgiWorkerFetch(opts);
+  const server = runtime.serve({ port, fetch });
+
+  if (!opts.quiet) {
+    const base = `http://localhost:${server.port}`;
+    console.log(`${opts.name} VGI HTTP worker listening on ${base}`);
+    console.log(`  landing page   ${base}/`);
+    console.log(`  describe.json  ${base}/describe.json`);
+    console.log(`  health         ${base}/health`);
+    console.log(`  attach         ATTACH '${opts.name}' AS ${opts.name} (TYPE vgi, LOCATION '${base}');`);
+  }
+  return server;
+}

package/src/worker-cf-entry.ts

@@ -13,57 +13,8 @@
 // `createVgiFetch` rather than a hard-coded singleton, so a CF Worker module
 // can compose multiple registries the same way the Bun worker does.
 
-import { createHttpHandler, unpackStateToken, type Protocol } from "@query-farm/vgi-rpc";
-import { arrowStateSerializer } from "./protocol/state-serializer.js";
-import { buildVgiProtocol, type ProtocolConfig } from "./protocol/dispatch.js";
-
-export interface VgiFetchOptions {
-  /** Wire-protocol config (registry + catalogInterface). */
-  protocol: Omit<ProtocolConfig, "recoverExchangeState">;
-  /** HMAC key for state-token signing. Pass a stable, secret 32-byte key
-   *  (e.g. derived from a Wrangler secret). Required because Workers don't
-   *  preserve in-memory state across requests/instances. */
-  signingKey: Uint8Array;
-  /** State-token TTL in seconds (default 3600). */
-  tokenTtl?: number;
-  /** URL path prefix for VGI requests (default "/vgi"). */
-  prefix?: string;
-  /** Server ID for state-token attribution (default "vgi-cf"). */
-  serverId?: string;
-}
-
-/**
- * Build a fetch handler suitable for `export default { fetch }` in a CF
- * Worker module. The returned handler is async-safe across Workers'
- * isolate-per-request execution model — all state round-trips through the
- * signed state token created here.
- */
-export function createVgiFetch(opts: VgiFetchOptions): (req: Request) => Promise<Response> {
-  const tokenTtl = opts.tokenTtl ?? 3600;
-  const prefix = opts.prefix ?? "/vgi";
-  const serverId = opts.serverId ?? "vgi-cf";
-
-  const protocol: Protocol = buildVgiProtocol({
-    signingKey: opts.signingKey,
-    ...opts.protocol,
-    recoverExchangeState: async (opaqueData: Uint8Array) => {
-      const tokenString = new TextDecoder().decode(opaqueData);
-      // principal binding is enforced by the HTTP handler on the request that
-      // carried this token; the recovery path itself is not principal-scoped.
-      const unpacked = await unpackStateToken(tokenString, opts.signingKey, tokenTtl, undefined);
-      return arrowStateSerializer.deserialize(unpacked.stateBytes);
-    },
-  });
-
-  const handler = createHttpHandler(protocol, {
-    prefix,
-    serverId,
-    tokenKey: opts.signingKey,
-    tokenTtl,
-    stateSerializer: arrowStateSerializer,
-  });
-  return async (req: Request) => handler(req);
-}
+export { createVgiFetch } from "./http/fetch.js";
+export type { VgiFetchOptions } from "./http/fetch.js";
 
 // Re-export the public types CF Worker authors need to wire a registry +
 // catalog. They import from "vgi/worker-cf" rather than from "vgi" directly
@@ -102,6 +53,11 @@ export type {
 
 export type { ProtocolConfig } from "./protocol/dispatch.js";
 
+// Landing surface. CF workers pass the provider as `landingDescribe` so
+// `GET /` serves the standardized VGI landing page for the worker's catalog.
+export { createLandingDescribe } from "./http/describe-json.js";
+export type { LandingDescribeProvider, WorkerDescribeInfo } from "./http/describe-json.js";
+
 // Backend-agnostic Arrow facade. Same source resolves to arrow-js on
 // Node/Bun and flechette under workerd/worker/browser via the package's
 // `#arrow-impl` conditional import. Worker authors should always go