@gscdump/lakehouse 4.2.0 → 4.2.2

package/dist/catalog-cache.d.mts

@@ -13,12 +13,14 @@ export interface CatalogCache {
   /** Optional warning sink for best-effort cache driver failures. */
   onError?: (operation: 'get' | 'set' | 'remove', key: string, error: unknown) => void;
 }
+/** Outcome of one cache read, including misses that still permit a fresh load. */
+export type CatalogCacheGetOutcome = 'hit' | 'miss' | 'expired' | 'invalid' | 'error';
 /**
  * Read a cached value. Returns `undefined` on a miss, an expired entry, a
  * malformed box, or any driver error (the cache is best-effort: a read failure
  * degrades to a fresh load, never to an error).
  */
-export declare function cacheGet<T>(cache: CatalogCache, key: string, now: number): Promise<T | undefined>;
+export declare function cacheGet<T>(cache: CatalogCache, key: string, now: number, onOutcome?: (outcome: CatalogCacheGetOutcome) => void): Promise<T | undefined>;
 /**
  * Write a cached value with an embedded expiry and a forwarded driver TTL.
  *

package/dist/catalog-cache.mjs

@@ -6,12 +6,37 @@ function reportCatalogCacheError(cache, operation, key, error) {
 		console.warn(`[gscdump/lakehouse] cache error reporter failed during ${operation} for ${key}`, reportError);
 	}
 }
-async function cacheGet(cache, key, now) {
-	const boxed = await cache.storage.getItem(key).catch((error) => {
+async function cacheGet(cache, key, now, onOutcome) {
+	const reportOutcome = (outcome) => {
+		try {
+			onOutcome?.(outcome);
+		} catch {}
+	};
+	const read = await cache.storage.getItem(key).then((boxed) => ({
+		_tag: "Ok",
+		boxed
+	}), (error) => {
 		reportCatalogCacheError(cache, "get", key, error);
-		return null;
+		return { _tag: "Error" };
 	});
-	if (!boxed || typeof boxed.exp !== "number" || boxed.exp <= now) return void 0;
+	if (read._tag === "Error") {
+		reportOutcome("error");
+		return;
+	}
+	const { boxed } = read;
+	if (!boxed) {
+		reportOutcome("miss");
+		return;
+	}
+	if (typeof boxed.exp !== "number" || boxed.v === void 0) {
+		reportOutcome("invalid");
+		return;
+	}
+	if (boxed.exp <= now) {
+		reportOutcome("expired");
+		return;
+	}
+	reportOutcome("hit");
 	return boxed.v;
 }
 function cachePut(cache, key, value, ttlMs, now) {

package/dist/catalog.d.mts

@@ -93,6 +93,8 @@ export interface ConnectIcebergOptions {
   cache?: CatalogCache;
   /** Injectable clock for the cache TTL. Defaults to `Date.now`. */
   clock?: () => number;
+  /** Optional connection-stage timings. Spans carry no catalog coordinates. */
+  profiler?: QueryProfiler;
 }
 /**
  * Connect to the R2 Data Catalog: a REST catalog context + a signed S3

package/dist/catalog.mjs

@@ -35,6 +35,20 @@ function manifestReadCacheFor(conn, namespace, table, metadata) {
 	}
 	return cache;
 }
+function startConnectSpan(profiler, name) {
+	if (!profiler) return void 0;
+	try {
+		const end = profiler.start(name);
+		if (!end) return void 0;
+		return (meta) => {
+			try {
+				end(meta);
+			} catch {}
+		};
+	} catch {
+		return;
+	}
+}
 let icebirdWriteModule;
 function useIcebirdWriteModule() {
 	icebirdWriteModule ??= import("./_virtual/node_modules/.pnpm/icebird@0.8.30_patch_hash=a400e343a199b1ca18601f96348011745ac6518fc07ffa71d5adfdd2ccc7d14f/node_modules/icebird/src/write/write.mjs");
@@ -49,7 +63,12 @@ async function connectIcebergCatalog(config, opts = {}) {
 	const requestInit = { headers: { Authorization: `Bearer ${config.catalogToken}` } };
 	let catalog;
 	if (opts.cache) {
-		const cached = await cacheGet(opts.cache, catalogConfigKey(config), now);
+		const endCache = startConnectSpan(opts.profiler, "catalog.config.cache");
+		const cacheRead = { outcome: "miss" };
+		const cached = await cacheGet(opts.cache, catalogConfigKey(config), now, (outcome) => {
+			cacheRead.outcome = outcome;
+		});
+		endCache?.({ outcome: cacheRead.outcome === "hit" && !cached ? "invalid" : cacheRead.outcome });
 		if (cached) catalog = Object.freeze({
 			type: "rest",
 			url: cached.url,
@@ -60,11 +79,18 @@ async function connectIcebergCatalog(config, opts = {}) {
 		});
 	}
 	if (!catalog) {
-		catalog = await restCatalogConnect({
-			url: config.catalogUri,
-			warehouse: config.warehouse,
-			requestInit
-		});
+		const endRest = startConnectSpan(opts.profiler, "catalog.config.rest");
+		let restOutcome = "error";
+		try {
+			catalog = await restCatalogConnect({
+				url: config.catalogUri,
+				warehouse: config.warehouse,
+				requestInit
+			});
+			restOutcome = "ok";
+		} finally {
+			endRest?.({ outcome: restOutcome });
+		}
 		if (opts.cache) {
 			const toCache = {
 				url: catalog.url,
@@ -72,7 +98,12 @@ async function connectIcebergCatalog(config, opts = {}) {
 				defaults: catalog.defaults,
 				overrides: catalog.overrides
 			};
-			await cachePut(opts.cache, catalogConfigKey(config), toCache, CATALOG_CONFIG_TTL_MS, now);
+			const endWrite = startConnectSpan(opts.profiler, "catalog.config.write");
+			try {
+				await cachePut(opts.cache, catalogConfigKey(config), toCache, CATALOG_CONFIG_TTL_MS, now);
+			} finally {
+				endWrite?.({ deferred: opts.cache.defer != null });
+			}
 		}
 	}
 	const cacheScope = catalogCacheScope(config);

package/dist/partition-prune.d.mts

@@ -11,13 +11,9 @@ export type ManifestPartitionFilter = (partitions: IcebergFieldSummary[] | undef
 /**
  * One identity/dims value to prune an `identity`-transform partition field by.
  *
- * `'int32'`-encoded fields are deliberately NOT pruned here (mirrors the
- * original engine behavior): an INT column's bound bytes are a 4-byte int, but
- * per-team catalogs are single-tenant, so identity pruning on them saves ~nothing
- * — the per-file partition check in the resolver remains the authoritative
- * correctness filter. Only `'string'`-encoded identity fields are pruned by
- * lexicographic UTF-8 bound comparison (the truncated-string-stats case R2 SQL
- * needs the workaround for).
+ * Identity summaries use the declared field encoding: UTF-8 for strings and
+ * four-byte little-endian for INT. Unknown bounds keep the manifest. The
+ * per-file partition check remains the authoritative correctness filter.
  */
 export interface PartitionValueMatch {
   /** Partition field name as declared in the partition spec (e.g. `'site_id'`). */

package/dist/partition-prune.mjs

@@ -7,11 +7,12 @@ function decodeString(bytes) {
 	const u = toUint8(bytes);
 	return u == null ? null : UTF8_DECODER.decode(u);
 }
-function decodeMonthInt(bytes) {
+function decodeInt32(bytes) {
 	const u = toUint8(bytes);
-	if (u == null) return null;
+	if (u?.byteLength !== 4) return null;
 	return new DataView(u.buffer, u.byteOffset, u.byteLength).getInt32(0, true);
 }
+const decodeMonthInt = decodeInt32;
 function buildManifestPartitionFilter(partitionSpec, matches, wantedMonths) {
 	const fieldIndex = (name) => partitionSpec.findIndex((f) => f.name === name || f.sourceColumn === name);
 	const monthFieldIndex = partitionSpec.findIndex((f) => f.transform === "month");
@@ -23,6 +24,14 @@ function buildManifestPartitionFilter(partitionSpec, matches, wantedMonths) {
 			value: String(match.value)
 		}];
 	});
+	const intMatches = matches.flatMap((match) => {
+		if (match.encoding !== "int32" || typeof match.value !== "number" || !Number.isInteger(match.value) || match.value < -2147483648 || match.value > 2147483647) return [];
+		const index = fieldIndex(match.field);
+		return index < 0 || partitionSpec[index]?.transform !== "identity" ? [] : [{
+			index,
+			value: match.value
+		}];
+	});
 	const wantedMonthValues = wantedMonths ? [...wantedMonths].filter(Number.isFinite).sort((a, b) => a - b) : [];
 	const hasWantedMonthInRange = (lo, hi) => {
 		let left = 0;
@@ -43,6 +52,13 @@ function buildManifestPartitionFilter(partitionSpec, matches, wantedMonths) {
 			const hi = decodeString(summary.upper_bound);
 			if (lo != null && hi != null && (match.value < lo || match.value > hi)) return false;
 		}
+		for (const match of intMatches) {
+			const summary = partitions[match.index];
+			if (!summary || summary.lower_bound == null || summary.upper_bound == null) continue;
+			const lo = decodeInt32(summary.lower_bound);
+			const hi = decodeInt32(summary.upper_bound);
+			if (lo != null && hi != null && lo <= hi && (match.value < lo || match.value > hi)) return false;
+		}
 		if (wantedMonthValues.length > 0 && monthFieldIndex >= 0) {
 			const monthSummary = partitions[monthFieldIndex];
 			if (monthSummary && (monthSummary.lower_bound != null || monthSummary.upper_bound != null)) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/lakehouse",
   "type": "module",
-  "version": "4.2.0",
+  "version": "4.2.2",
   "description": "Dataset-agnostic Iceberg lakehouse layer + dataset registry for R2 Data Catalog producers (ADR-0021).",
   "author": {
     "name": "Harlan Wilton",