@query-farm/vgi 0.15.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.15.0",
+  "version": "0.18.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.12.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.12.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/catalog/descriptors.ts

@@ -60,18 +60,24 @@ export interface TableDescriptor {
    */
   statisticsCacheMaxAgeSeconds?: number | null;
   /**
-   * Dotted-path column references that MUST appear in a WHERE expression for
-   * any scan of this table. Top-level names (`"country"`) or struct subfields
-   * (`"bbox.xmin"`, `"nested.outer.inner"`). Empty/undefined (default) means
-   * no enforcement — the zero-cost fast path for every existing table.
+   * Required WHERE-filter groups in conjunctive normal form — an AND (outer
+   * list) of OR-groups (inner lists) of dotted-path column references that MUST
+   * appear in a WHERE expression for any scan of this table. A group is
+   * satisfied when any one of its paths has a filter; every group must be
+   * satisfied. So `[["accession_number"], ["ticker", "cik"]]` means
+   * "accession_number AND one of (ticker, cik)"; a single-path group
+   * `[["country"]]` is a plain mandatory filter. Paths are top-level names
+   * (`"country"`) or struct subfields (`"bbox.xmin"`, `"nested.outer.inner"`).
+   * Empty/undefined (default) means no enforcement — the zero-cost fast path
+   * for every existing table.
    *
    * Satisfaction is prefix-based: a present filter on a shorter path satisfies
    * any required path it is a prefix of. So a whole-struct filter on `bbox`
    * satisfies all of `bbox.xmin` / `.xmax` / `.ymin` / `.ymax`. The VGI DuckDB
-   * extension's optimizer pass consults this list at bind time and throws a
-   * `BinderException` listing any unsatisfied paths.
+   * extension's optimizer pass consults this at bind time and throws a
+   * `BinderException` listing any unsatisfied groups.
    */
-  requiredFieldFilterPaths?: string[];
+  requiredFilters?: string[][];
   supportsTimeTravel?: boolean;
   /**
    * Inline cardinality estimate/max surfaced through TableInfo. When set,

package/src/catalog/read-only.ts

@@ -235,26 +235,34 @@ export class ReadOnlyCatalogInterface extends CatalogInterface {
       const pkIndices = resolveIndexGroups(colSchema, t.primaryKey);
       const fkBytes = serializeForeignKeys(t.foreignKey, name);
 
-      // Validate required_field_filter_paths: the leading dotted segment of
-      // each path must be a real column on this table. Struct subfield
+      // Validate required_filters: an AND (outer list) of OR-groups (inner
+      // lists). Each OR-group must be non-empty, and the leading dotted segment
+      // of each path must be a real column on this table. Struct subfield
       // validity is not checked here — DuckDB's binder catches typos at scan
       // time, and the descriptor doesn't unpack STRUCT subfields. (Mirrors
       // vgi-python's Table descriptor validation.)
-      const requiredFieldFilterPaths = t.requiredFieldFilterPaths ?? [];
-      if (requiredFieldFilterPaths.length > 0) {
+      const requiredFilters = t.requiredFilters ?? [];
+      if (requiredFilters.length > 0) {
         const columnNames = new Set(colSchema.fields.map((f) => f.name));
-        for (const path of requiredFieldFilterPaths) {
-          if (!path) {
+        for (const group of requiredFilters) {
+          if (!group || group.length === 0) {
             throw new Error(
-              `Table '${t.name}': requiredFieldFilterPaths must not contain empty strings`
+              `Table '${t.name}': requiredFilters must not contain empty groups`
             );
           }
-          const head = path.split(".", 1)[0];
-          if (!columnNames.has(head)) {
-            throw new Error(
-              `Table '${t.name}': requiredFieldFilterPaths path '${path}' references ` +
-                `unknown column '${head}'. Available columns: ${[...columnNames].sort().join(", ")}`
-            );
+          for (const path of group) {
+            if (!path) {
+              throw new Error(
+                `Table '${t.name}': requiredFilters must not contain empty strings`
+              );
+            }
+            const head = path.split(".", 1)[0];
+            if (!columnNames.has(head)) {
+              throw new Error(
+                `Table '${t.name}': requiredFilters path '${path}' references ` +
+                  `unknown column '${head}'. Available columns: ${[...columnNames].sort().join(", ")}`
+              );
+            }
           }
         }
       }
@@ -292,7 +300,7 @@ export class ReadOnlyCatalogInterface extends CatalogInterface {
         cardinality_max: t.inlinedCardinality
           ? Number(t.inlinedCardinality.max)
           : null,
-        required_field_filter_paths: requiredFieldFilterPaths,
+        required_filters: requiredFilters,
       };
     }));
   }

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/generated/vgi-client.ts

@@ -2,7 +2,7 @@
 // GENERATED by vgi.codegen.ts_client. DO NOT EDIT BY HAND.
 //
 // Generator: vgi-gen-ts-client v1
-// Content hash: 5ddab596625f
+// Content hash: f3ac87321a0c
 //
 // To regenerate:
 //   uv run --project ~/Development/vgi-python vgi-gen-ts-client \
@@ -84,7 +84,7 @@ export interface TableInfo {
   cardinality_max?: number | null;
   column_statistics?: Uint8Array | null;
   bind_result?: Uint8Array | null;
-  required_field_filter_paths: string[];
+  required_filters: string[][];
 }
 
 export interface ViewInfo {

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

@@ -2,7 +2,7 @@
 // GENERATED by vgi.codegen.ts_schemas. DO NOT EDIT BY HAND.
 //
 // Generator: vgi-gen-ts-schemas v2
-// Content hash: 673bfdc9573a
+// Content hash: b3c99cc5fac8
 //
 // To regenerate:
 //   uv run --project ~/Development/vgi-python vgi-gen-ts-schemas \
@@ -70,7 +70,7 @@ export const TableInfoSchema = schema([
   field("cardinality_max", int64(), false),
   field("column_statistics", binary(), false),
   field("bind_result", binary(), false),
-  field("required_field_filter_paths", list(field("item", utf8(), true)), false),
+  field("required_filters", list(field("item", list(field("item", utf8(), true)), true)), false),
 ]);
 
 // Origin: ViewInfo

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";