@gscdump/lakehouse 1.4.0 → 1.4.1

package/dist/catalog-cache.d.mts

@@ -0,0 +1,32 @@
+import { a as Storage } from "./node_modules/.pnpm/unstorage@1.17.5_aws4fetch@1.0.20_db0@0.3.4_ioredis@5.10.1_supports-color@10.2.2_/node_modules/unstorage/dist/shared/unstorage.DqlWKU2I.mjs";
+import "./node_modules/.pnpm/unstorage@1.17.5_aws4fetch@1.0.20_db0@0.3.4_ioredis@5.10.1_supports-color@10.2.2_/node_modules/unstorage/dist/index2.mjs";
+/** Injected catalog cache: an unstorage `Storage` plus an optional defer hook. */
+interface CatalogCache {
+  /** unstorage storage instance — the driver is the caller's choice. */
+  storage: Storage;
+  /**
+   * Optional hook to run a cache WRITE off the response critical path, e.g.
+   * Cloudflare's `ctx.waitUntil`. When omitted the writer awaits the put
+   * inline so it is never cut off when the response returns.
+   */
+  defer?: (write: Promise<unknown>) => void;
+  /** Optional warning sink for best-effort cache driver failures. */
+  onError?: (operation: 'get' | 'set' | 'remove', key: string, error: unknown) => void;
+}
+/**
+ * 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).
+ */
+declare function cacheGet<T>(cache: CatalogCache, key: string, now: number): Promise<T | undefined>;
+/**
+ * Write a cached value with an embedded expiry and a forwarded driver TTL.
+ *
+ * Returns the write promise. With a `defer` hook the write is handed to the
+ * hook and a resolved promise is returned (the response is not blocked on it);
+ * without one the write promise is returned for the caller to await, so a
+ * fire-and-forget put is never silently dropped. Driver errors are reported
+ * through `onError` (or `console.warn`) but do not fail the read.
+ */
+declare function cachePut<T>(cache: CatalogCache, key: string, value: T, ttlMs: number, now: number): Promise<void>;
+export { CatalogCache, cacheGet, cachePut };

package/dist/catalog-cache.mjs

@@ -0,0 +1,31 @@
+function reportCatalogCacheError(cache, operation, key, error) {
+	try {
+		if (cache.onError) cache.onError(operation, key, error);
+		else console.warn(`[gscdump/lakehouse] cache ${operation} failed for ${key}`, error);
+	} catch (reportError) {
+		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) => {
+		reportCatalogCacheError(cache, "get", key, error);
+		return null;
+	});
+	if (!boxed || typeof boxed.exp !== "number" || boxed.exp <= now) return void 0;
+	return boxed.v;
+}
+function cachePut(cache, key, value, ttlMs, now) {
+	const boxed = {
+		v: value,
+		exp: now + ttlMs
+	};
+	const write = cache.storage.setItem(key, boxed, { ttl: Math.ceil(ttlMs / 1e3) }).catch((error) => {
+		reportCatalogCacheError(cache, "set", key, error);
+	});
+	if (cache.defer) {
+		cache.defer(write);
+		return Promise.resolve();
+	}
+	return write;
+}
+export { cacheGet, cachePut, reportCatalogCacheError };

package/dist/{_chunks/catalog.d.mts → catalog.d.mts}

@@ -1,68 +1,10 @@
-import { Storage } from "./libs/unstorage.mjs";
-import { IcebergColumnType, IcebergPartitionField, IcebergS3Config } from "./schema.mjs";
-import { cachingResolver, icebergAppend, restCatalogConnect } from "./libs/icebird.mjs";
-/** Injected catalog cache: an unstorage `Storage` plus an optional defer hook. */
-interface CatalogCache {
-  /** unstorage storage instance — the driver is the caller's choice. */
-  storage: Storage;
-  /**
-   * Optional hook to run a cache WRITE off the response critical path, e.g.
-   * Cloudflare's `ctx.waitUntil`. When omitted the writer awaits the put
-   * inline so it is never cut off when the response returns.
-   */
-  defer?: (write: Promise<unknown>) => void;
-  /** Optional warning sink for best-effort cache driver failures. */
-  onError?: (operation: 'get' | 'set' | 'remove', key: string, error: unknown) => void;
-}
-/**
- * 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).
- */
-declare function cacheGet<T>(cache: CatalogCache, key: string, now: number): Promise<T | undefined>;
-/**
- * Write a cached value with an embedded expiry and a forwarded driver TTL.
- *
- * Returns the write promise. With a `defer` hook the write is handed to the
- * hook and a resolved promise is returned (the response is not blocked on it);
- * without one the write promise is returned for the caller to await, so a
- * fire-and-forget put is never silently dropped. Driver errors are reported
- * through `onError` (or `console.warn`) but do not fail the read.
- */
-declare function cachePut<T>(cache: CatalogCache, key: string, value: T, ttlMs: number, now: number): Promise<void>;
-/** Minimal shape of an icebird manifest-list `partitions` field-summary. */
-interface IcebergFieldSummary {
-  contains_null: boolean;
-  contains_nan?: boolean | null;
-  lower_bound?: Uint8Array | null;
-  upper_bound?: Uint8Array | null;
-}
-/** Predicate handed to icebird's patched `icebergManifests({ partitionFilter })`. */
-type ManifestPartitionFilter = (partitions: IcebergFieldSummary[] | undefined) => boolean;
-/**
- * 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).
- */
-interface PartitionValueMatch {
-  /** Partition field name as declared in the partition spec (e.g. `'site_id'`). */
-  field: string;
-  value: string | number;
-  encoding: 'string' | 'int32';
-}
-/**
- * Build the `partitionFilter` predicate for a slice of `matches` (identity/dims
- * value equality) plus an optional `wantedMonths` set (for a `month`-transform
- * field in `partitionSpec`). Returns `false` to skip a manifest, `true` to keep
- * it. Keep-all when a manifest carries no `partitions` summaries.
- */
-declare function buildManifestPartitionFilter(partitionSpec: readonly IcebergPartitionField[], matches: readonly PartitionValueMatch[], wantedMonths?: ReadonlySet<number>): ManifestPartitionFilter;
+import { CatalogCache } from "./catalog-cache.mjs";
+import { IcebergColumnType, IcebergS3Config } from "./schema.mjs";
+import { PartitionValueMatch } from "./partition-prune.mjs";
+import { icebergAppend } from "./node_modules/.pnpm/icebird@0.8.15_patch_hash_d1902372376af18885e7c7dce807f1ecab86c2f86a9d1ff65d51e3b63b64b057/node_modules/icebird/types/write/write.mjs";
+import { restCatalogConnect } from "./node_modules/.pnpm/icebird@0.8.15_patch_hash_d1902372376af18885e7c7dce807f1ecab86c2f86a9d1ff65d51e3b63b64b057/node_modules/icebird/types/catalog/rest.mjs";
+import { cachingResolver } from "./node_modules/.pnpm/icebird@0.8.15_patch_hash_d1902372376af18885e7c7dce807f1ecab86c2f86a9d1ff65d51e3b63b64b057/node_modules/icebird/types/fetch.mjs";
+import "./node_modules/.pnpm/icebird@0.8.15_patch_hash_d1902372376af18885e7c7dce807f1ecab86c2f86a9d1ff65d51e3b63b64b057/node_modules/icebird/types/index.mjs";
 /** icebird's lowercase Iceberg primitive types (subset we use). */
 type IcebergPrimitiveType = 'string' | 'int' | 'long' | 'double' | 'date' | 'boolean';
 /** A field in an icebird table `Schema`. */
@@ -271,4 +213,4 @@ declare function invalidateSnapshotRef(cache: CatalogCache, namespace: string, t
  * the def's own spec + identity/dims values.
  */
 declare function resolveIcebergDataFiles(conn: IcebergConnection, opts: ResolveIcebergDataFilesOptions): Promise<IcebergListedDataFile[]>;
-export { CatalogCache, CommitRetryOptions, ConnectIcebergOptions, ICEBERG_TYPE_MAP, IcebergCatalogConfig, IcebergConnection, IcebergFieldSummary, IcebergListedDataFile, IcebergPartitionSpec, IcebergPartitionSpecField, IcebergPrimitiveType, IcebergSchema, IcebergSchemaField, IcebergSortOrder, IcebergSortOrderField, IcebergTableOpResult, ManifestPartitionFilter, PartitionValueMatch, QueryProfiler, ResolveIcebergDataFilesOptions, buildManifestPartitionFilter, cacheGet, cachePut, catalogCacheScope, connectIcebergCatalog, dropIcebergTables, ensureIcebergNamespace, icebergAppendRetrying, invalidateSnapshotRef, isCommitRateLimited, listIcebergTables, resolveIcebergDataFiles };
+export { CommitRetryOptions, ConnectIcebergOptions, ICEBERG_TYPE_MAP, IcebergCatalogConfig, IcebergConnection, IcebergListedDataFile, IcebergPartitionSpec, IcebergPartitionSpecField, IcebergPrimitiveType, IcebergSchema, IcebergSchemaField, IcebergSortOrder, IcebergSortOrderField, IcebergTableOpResult, QueryProfiler, ResolveIcebergDataFilesOptions, catalogCacheScope, connectIcebergCatalog, dropIcebergTables, ensureIcebergNamespace, icebergAppendRetrying, invalidateSnapshotRef, isCommitRateLimited, listIcebergTables, resolveIcebergDataFiles };

package/dist/{_chunks/catalog.mjs → catalog.mjs}

@@ -1,91 +1,12 @@
-import { stringifyBigintSafe } from "../bigint.mjs";
-import { cachingResolver, icebergAppend, icebergAppendBatches, icebergDropTable, icebergManifests, restCatalogConnect, restCatalogCreateNamespace, restCatalogListTables, restCatalogLoadTable, s3SignedResolver } from "./libs/icebird.mjs";
-function reportCatalogCacheError(cache, operation, key, error) {
-	try {
-		if (cache.onError) cache.onError(operation, key, error);
-		else console.warn(`[gscdump/lakehouse] cache ${operation} failed for ${key}`, error);
-	} catch (reportError) {
-		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) => {
-		reportCatalogCacheError(cache, "get", key, error);
-		return null;
-	});
-	if (!boxed || typeof boxed.exp !== "number" || boxed.exp <= now) return void 0;
-	return boxed.v;
-}
-function cachePut(cache, key, value, ttlMs, now) {
-	const boxed = {
-		v: value,
-		exp: now + ttlMs
-	};
-	const write = cache.storage.setItem(key, boxed, { ttl: Math.ceil(ttlMs / 1e3) }).catch((error) => {
-		reportCatalogCacheError(cache, "set", key, error);
-	});
-	if (cache.defer) {
-		cache.defer(write);
-		return Promise.resolve();
-	}
-	return write;
-}
-function toUint8(bytes) {
-	if (bytes == null) return null;
-	return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
-}
-const UTF8_DECODER = new TextDecoder();
-function decodeString(bytes) {
-	const u = toUint8(bytes);
-	return u == null ? null : UTF8_DECODER.decode(u);
-}
-function decodeMonthInt(bytes) {
-	const u = toUint8(bytes);
-	if (u == null) return null;
-	return new DataView(u.buffer, u.byteOffset, u.byteLength).getInt32(0, true);
-}
-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");
-	const stringMatches = matches.flatMap((match) => {
-		if (match.encoding !== "string") return [];
-		const index = fieldIndex(match.field);
-		return index < 0 ? [] : [{
-			index,
-			value: String(match.value)
-		}];
-	});
-	const wantedMonthValues = wantedMonths ? [...wantedMonths].filter(Number.isFinite).sort((a, b) => a - b) : [];
-	const hasWantedMonthInRange = (lo, hi) => {
-		let left = 0;
-		let right = wantedMonthValues.length;
-		while (left < right) {
-			const middle = left + right >>> 1;
-			if (wantedMonthValues[middle] < lo) left = middle + 1;
-			else right = middle;
-		}
-		return left < wantedMonthValues.length && wantedMonthValues[left] <= hi;
-	};
-	return (partitions) => {
-		if (!partitions || partitions.length === 0) return true;
-		for (const match of stringMatches) {
-			const summary = partitions[match.index];
-			if (!summary || summary.lower_bound == null && summary.upper_bound == null) continue;
-			const lo = decodeString(summary.lower_bound);
-			const hi = decodeString(summary.upper_bound);
-			if (lo != null && hi != null && (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)) {
-				const lo = decodeMonthInt(monthSummary.lower_bound);
-				const hi = decodeMonthInt(monthSummary.upper_bound);
-				if (lo != null && hi != null && !hasWantedMonthInRange(lo, hi)) return false;
-			}
-		}
-		return true;
-	};
-}
+import { stringifyBigintSafe } from "./bigint.mjs";
+import { cachingResolver } from "./node_modules/.pnpm/icebird@0.8.15_patch_hash_d1902372376af18885e7c7dce807f1ecab86c2f86a9d1ff65d51e3b63b64b057/node_modules/icebird/src/fetch.mjs";
+import { restCatalogConnect, restCatalogCreateNamespace, restCatalogListTables, restCatalogLoadTable } from "./node_modules/.pnpm/icebird@0.8.15_patch_hash_d1902372376af18885e7c7dce807f1ecab86c2f86a9d1ff65d51e3b63b64b057/node_modules/icebird/src/catalog/rest.mjs";
+import { icebergManifests } from "./node_modules/.pnpm/icebird@0.8.15_patch_hash_d1902372376af18885e7c7dce807f1ecab86c2f86a9d1ff65d51e3b63b64b057/node_modules/icebird/src/manifest.mjs";
+import { icebergAppend, icebergAppendBatches, icebergDropTable } from "./node_modules/.pnpm/icebird@0.8.15_patch_hash_d1902372376af18885e7c7dce807f1ecab86c2f86a9d1ff65d51e3b63b64b057/node_modules/icebird/src/write/write.mjs";
+import { s3SignedResolver } from "./node_modules/.pnpm/icebird@0.8.15_patch_hash_d1902372376af18885e7c7dce807f1ecab86c2f86a9d1ff65d51e3b63b64b057/node_modules/icebird/src/s3.mjs";
+import "./node_modules/.pnpm/icebird@0.8.15_patch_hash_d1902372376af18885e7c7dce807f1ecab86c2f86a9d1ff65d51e3b63b64b057/node_modules/icebird/src/index.mjs";
+import { cacheGet, cachePut, reportCatalogCacheError } from "./catalog-cache.mjs";
+import { buildManifestPartitionFilter } from "./partition-prune.mjs";
 const ICEBERG_TYPE_MAP = {
 	STRING: "string",
 	INT: "int",
@@ -429,4 +350,4 @@ async function resolveIcebergDataFiles(conn, opts) {
 	}
 	return out;
 }
-export { ICEBERG_TYPE_MAP, buildManifestPartitionFilter, cacheGet, cachePut, catalogCacheScope, connectIcebergCatalog, dropIcebergTables, ensureIcebergNamespace, icebergAppendBatchesRetrying, icebergAppendRetrying, invalidateSnapshotRef, isCommitRateLimited, listIcebergTables, resolveIcebergDataFiles };
+export { ICEBERG_TYPE_MAP, catalogCacheScope, connectIcebergCatalog, dropIcebergTables, ensureIcebergNamespace, icebergAppendBatchesRetrying, icebergAppendRetrying, invalidateSnapshotRef, isCommitRateLimited, listIcebergTables, resolveIcebergDataFiles };

package/dist/dataset.d.mts

@@ -0,0 +1,162 @@
+import { CatalogCache } from "./catalog-cache.mjs";
+import { IcebergColumnType, IcebergPartitionField, IcebergTableSpec } from "./schema.mjs";
+import { ManifestPartitionFilter, PartitionValueMatch } from "./partition-prune.mjs";
+import { CommitRetryOptions, ConnectIcebergOptions, IcebergCatalogConfig, IcebergConnection, IcebergListedDataFile, IcebergPartitionSpec, IcebergSchema, IcebergSortOrder, IcebergTableOpResult, QueryProfiler } from "./catalog.mjs";
+/**
+ * Closed identity shapes (ADR-0021 amendments 2 + 4). `'site-int'` is the
+ * team-scoped numeric Catalog Site Id (nuxtseo ADR-0091) stored under the
+ * fixed column name `site_id`. `'columns'` is the general N-column identity
+ * with per-column encoding, replacing the original opaque `'custom'` shape.
+ */
+type DatasetIdentity = {
+  kind: 'site-int';
+  encoding?: 'int' | 'string';
+} | {
+  kind: 'columns';
+  columns: readonly {
+    name: string;
+    encoding: 'int32' | 'string';
+  }[];
+};
+/** A per-slice dimension (GSC's `searchType`). Absent for plain snapshot datasets. */
+interface DatasetDim {
+  toPartitionValue: (v: string) => string | number;
+  /** Required (amendment 5) — how the reader decodes this column's manifest bounds. */
+  boundEncoding: 'int32' | 'string';
+}
+interface IcebergDatasetColumnDef {
+  name: string;
+  type: IcebergColumnType;
+  required: boolean;
+}
+interface IcebergDatasetLedger {
+  key: readonly string[];
+}
+interface IcebergDatasetDef {
+  namespace: string;
+  table: string;
+  identity: DatasetIdentity;
+  /** Extra per-slice dimensions; absent for snapshot datasets. */
+  dims?: Record<string, DatasetDim>;
+  /** Data columns (non-identity, non-dims) — includes any partition source column (e.g. `date`). */
+  columns: readonly IcebergDatasetColumnDef[];
+  /** Partition fields; identity columns must appear here. */
+  partition: readonly IcebergPartitionField[];
+  /** Natural-key columns. Full dedupe key = identity + dims + naturalKey (amendment 3). */
+  naturalKey: readonly string[];
+  clusterKey?: readonly string[];
+  /** Consumer-owned exactly-once ledger shape — folded into `appendSink().close()` (amendment 6). */
+  ledger?: IcebergDatasetLedger;
+}
+/**
+ * Derive the full {@link IcebergTableSpec} from a dataset def. Field ids are
+ * assigned sequentially in ONE fixed order — identity columns, then dims
+ * columns, then declared data columns — starting at 1. This mirrors the
+ * engine's original `icebergTableSpec` contract (identity columns first, data
+ * columns from a fixed base) so a def-derived spec for an existing table
+ * (`crawl.pages`, `lighthouse.scans`, `dataforseo.keywords`) is BYTE-IDENTICAL
+ * to the frozen inline constants it replaces.
+ */
+declare function deriveTableSpec(def: IcebergDatasetDef): IcebergTableSpec;
+/**
+ * Convert a `YYYY-MM-DD` string / `Date` / already-numeric day-count to the
+ * integer "days since the Unix epoch" the Iceberg `date` type stores.
+ * hyparquet-writer mis-encodes Date-valued dictionary columns, so callers
+ * should feed this INTO their row before `appendRows`/`appendSink.emit` for
+ * any `month`-partitioned date column.
+ */
+declare function toIcebergDayCount(value: string | Date | number): number;
+/** Options shared by `appendRows` / `appendSink`. */
+interface AppendCommitOptions {
+  commitRetry?: CommitRetryOptions;
+}
+interface AppendSinkOptions extends AppendCommitOptions {
+  catalog: IcebergCatalogConfig;
+  connect?: ConnectIcebergOptions;
+  /** Invoked ONLY after a successful flush (amendment 6) — never on a failed/empty close. */
+  ledger?: {
+    record: () => Promise<void> | void;
+  };
+}
+interface AppendResult {
+  /** Rows accepted after the identity guard + dedupe (what was actually appended). */
+  accepted: number;
+  /** Rows dropped by the identity guard (missing/out-of-range required identity value). */
+  skipped: number;
+}
+type AppendBatchSource = () => Iterable<readonly Record<string, unknown>[]> | AsyncIterable<readonly Record<string, unknown>[]>;
+interface AppendBatchesOptions extends AppendCommitOptions {
+  /** Stable across job retries; recorded in snapshot metadata for landed checks. */
+  appendId: string;
+}
+interface AppendBatchesResult extends AppendResult {
+  /** False when this append id was already present before the call. */
+  committed: boolean;
+}
+interface AppendSinkCloseResult extends AppendResult {
+  flushed: boolean;
+  error?: unknown;
+}
+interface AppendSink {
+  emit: (rows: readonly Record<string, unknown>[]) => void;
+  close: () => Promise<AppendSinkCloseResult>;
+}
+interface ResolveDataFilesOptions {
+  cache?: CatalogCache;
+  clock?: () => number;
+  profiler?: QueryProfiler;
+}
+interface IcebergDataset {
+  readonly def: IcebergDatasetDef;
+  readonly tableSpec: IcebergTableSpec;
+  icebergSchema: () => IcebergSchema;
+  icebergPartitionSpec: () => IcebergPartitionSpec;
+  icebergSortOrder: () => IcebergSortOrder | undefined;
+  createTable: (conn: IcebergConnection) => Promise<IcebergTableOpResult[]>;
+  /**
+   * One-shot append over an EXISTING connection: identity INT32 guard, dedupe
+   * by identity+dims+naturalKey (last-wins), cluster pre-sort (if
+   * `clusterKey` is set), then a single `icebergAppendRetrying` commit. `rows`
+   * must already be in final storage-column shape — identity/dims/data
+   * columns keyed by their STORED column names, with any `month`-partitioned
+   * date column pre-converted via {@link toIcebergDayCount}.
+   */
+  appendRows: (conn: IcebergConnection, rows: readonly Record<string, unknown>[], opts?: AppendCommitOptions) => Promise<AppendResult>;
+  /**
+   * Lazily process bounded row batches, writing multiple data files into one
+   * append snapshot and one catalog commit. Dedupe keys must be disjoint
+   * across source batches.
+   */
+  appendBatches: (conn: IcebergConnection, source: AppendBatchSource, opts: AppendBatchesOptions) => Promise<AppendBatchesResult>;
+  /**
+   * PURE row processing — the identity INT32 guard, dedupe (identity+dims+
+   * naturalKey, last-wins) and cluster pre-sort `appendRows`/`appendSink`
+   * apply before committing, exposed standalone with NO network/icebird call.
+   * Lets a consumer that owns its own commit call-site (e.g. one still
+   * calling a frozen `icebergAppendRetrying` import directly, for test-mock
+   * compatibility) still route its dedupe/guard/sort logic through the
+   * dataset definition.
+   */
+  prepareRows: (rows: readonly Record<string, unknown>[]) => {
+    records: Record<string, unknown>[];
+    skipped: number;
+  };
+  /** Buffered multi-emit sink — owns its own connect/close lifecycle (ADR-0021's primary contract). */
+  appendSink: (opts: AppendSinkOptions) => AppendSink;
+  /** `PartitionValueMatch[]` for one identity value (+ optional dims), for manual manifest filtering. */
+  readerPredicate: (identity: string | number, dims?: Record<string, string>) => PartitionValueMatch[];
+  /** A ready-to-use manifest partition filter for one identity value + wanted months. */
+  partitionBoundFilter: (identity: string | number, months: ReadonlySet<number>, dims?: Record<string, string>) => ManifestPartitionFilter;
+  /** Resolve the data files for one identity value across a date range. */
+  resolveDataFiles: (conn: IcebergConnection, identity: string | number, range: {
+    start: string;
+    end: string;
+  }, dims?: Record<string, string>, opts?: ResolveDataFilesOptions) => Promise<IcebergListedDataFile[]>;
+}
+/**
+ * Declare an Iceberg dataset — one `namespace.table` — deriving its schema,
+ * partition spec, dedupe key, INT32 guard, append path, and reader helpers
+ * from the def. See {@link IcebergDatasetDef}.
+ */
+declare function defineIcebergDataset(def: IcebergDatasetDef): IcebergDataset;
+export { AppendBatchSource, AppendBatchesOptions, AppendBatchesResult, AppendCommitOptions, AppendResult, AppendSink, AppendSinkCloseResult, AppendSinkOptions, DatasetDim, DatasetIdentity, IcebergDataset, IcebergDatasetColumnDef, IcebergDatasetDef, IcebergDatasetLedger, ResolveDataFilesOptions, defineIcebergDataset, deriveTableSpec, toIcebergDayCount };