@gscdump/lakehouse 0.1.0

package/dist/index.mjs

@@ -0,0 +1,356 @@
+import { icebergCreateTable } from "./_chunks/libs/icebird.mjs";
+import { ICEBERG_TYPE_MAP, buildManifestPartitionFilter, cacheGet, cachePut, connectIcebergCatalog, dropIcebergTables, ensureIcebergNamespace, icebergAppendRetrying, listIcebergTables, resolveIcebergDataFiles } from "./_chunks/catalog.mjs";
+import process from "node:process";
+const INT32_MIN = -2147483648;
+const INT32_MAX = 2147483647;
+const DAY_MILLIS = 864e5;
+function identityColumnNames(identity) {
+	return identity.kind === "site-int" ? ["site_id"] : identity.columns.map((c) => c.name);
+}
+function identityEncodings(identity) {
+	const map = /* @__PURE__ */ new Map();
+	if (identity.kind === "site-int") map.set("site_id", (identity.encoding ?? "int") === "int" ? "int32" : "string");
+	else for (const c of identity.columns) map.set(c.name, c.encoding);
+	return map;
+}
+function identityColumnType(encoding) {
+	return encoding === "int32" ? "INT" : "STRING";
+}
+function deriveTableSpec(def) {
+	const encodings = identityEncodings(def.identity);
+	const idNames = identityColumnNames(def.identity);
+	const dimNames = def.dims ? Object.keys(def.dims) : [];
+	let fieldId = 1;
+	const columns = [];
+	for (const name of idNames) columns.push({
+		name,
+		type: identityColumnType(encodings.get(name)),
+		required: true,
+		fieldId: fieldId++
+	});
+	for (const name of dimNames) {
+		const enc = def.dims[name].boundEncoding;
+		columns.push({
+			name,
+			type: identityColumnType(enc),
+			required: true,
+			fieldId: fieldId++
+		});
+	}
+	for (const col of def.columns) columns.push({
+		name: col.name,
+		type: col.type,
+		required: col.required,
+		fieldId: fieldId++
+	});
+	return {
+		namespace: def.namespace,
+		table: def.table,
+		columns,
+		partitionSpec: def.partition,
+		naturalKey: def.naturalKey,
+		identityColumns: [
+			...idNames,
+			...dimNames,
+			...def.naturalKey
+		],
+		clusterKey: def.clusterKey
+	};
+}
+function icebergSchemaFromSpec(spec) {
+	return {
+		"type": "struct",
+		"schema-id": 0,
+		"fields": spec.columns.map((col) => ({
+			id: col.fieldId,
+			name: col.name,
+			required: col.required,
+			type: ICEBERG_TYPE_MAP[col.type]
+		}))
+	};
+}
+function icebergPartitionSpecFromSpec(spec) {
+	const fieldId = (name) => {
+		const col = spec.columns.find((c) => c.name === name);
+		if (!col) throw new Error(`lakehouse: table '${spec.table}' has no '${name}' column`);
+		return col.fieldId;
+	};
+	return {
+		"spec-id": 0,
+		"fields": spec.partitionSpec.map((p, i) => ({
+			"source-id": fieldId(p.sourceColumn),
+			"field-id": 1e3 + i,
+			"name": p.name,
+			"transform": p.transform
+		}))
+	};
+}
+function icebergSortOrderFromSpec(spec) {
+	if (!spec.clusterKey || spec.clusterKey.length === 0) return void 0;
+	const fieldId = (name) => {
+		const col = spec.columns.find((c) => c.name === name);
+		if (!col) throw new Error(`lakehouse: table '${spec.table}' has no '${name}' column`);
+		return col.fieldId;
+	};
+	return {
+		"order-id": 1,
+		"fields": spec.clusterKey.map((col) => ({
+			"source-id": fieldId(col),
+			"transform": "identity",
+			"direction": "asc",
+			"null-order": "nulls-last"
+		}))
+	};
+}
+function toIcebergDayCount(value) {
+	if (typeof value === "number") return value;
+	if (value instanceof Date) {
+		const ms = value.getTime();
+		if (Number.isNaN(ms)) throw new TypeError("toIcebergDayCount: invalid Date (NaN)");
+		return Math.floor(ms / DAY_MILLIS);
+	}
+	const ms = Date.parse(`${value}T00:00:00Z`);
+	if (Number.isNaN(ms)) throw new TypeError(`toIcebergDayCount: invalid date string '${value}'`);
+	return Math.floor(ms / DAY_MILLIS);
+}
+function coerceJsonSafe(value) {
+	return typeof value === "bigint" ? Number(value) : value;
+}
+function asInt32(value) {
+	if (typeof value !== "string" && typeof value !== "number" && typeof value !== "bigint") return null;
+	const n = Number(value);
+	if (!Number.isSafeInteger(n) || n < INT32_MIN || n > INT32_MAX) return null;
+	return n;
+}
+function buildRowProcessor(def, tableSpec) {
+	const idNames = identityColumnNames(def.identity);
+	const idEncodings = identityEncodings(def.identity);
+	const dimNames = def.dims ? Object.keys(def.dims) : [];
+	function guard(row) {
+		const out = {};
+		for (const name of idNames) {
+			const enc = idEncodings.get(name);
+			const raw = row[name];
+			if (enc === "int32") {
+				const n = asInt32(raw);
+				if (n === null) return null;
+				out[name] = n;
+			} else {
+				if (raw == null || raw === "") return null;
+				out[name] = String(raw);
+			}
+		}
+		for (const name of dimNames) out[name] = def.dims[name].toPartitionValue(String(row[name]));
+		for (const col of def.columns) out[col.name] = coerceJsonSafe(row[col.name]);
+		return out;
+	}
+	function dedupe(rows) {
+		if (rows.length < 2) return rows;
+		const keyCols = tableSpec.identityColumns;
+		const seen = /* @__PURE__ */ new Map();
+		for (const rec of rows) {
+			const k = keyCols.map((c) => `${rec[c] ?? ""}`).join("\0");
+			seen.set(k, rec);
+		}
+		return seen.size === rows.length ? rows : [...seen.values()];
+	}
+	function sort(rows) {
+		const cols = def.clusterKey;
+		if (!cols || cols.length === 0 || rows.length < 2) return rows;
+		return rows.slice().sort((a, b) => {
+			for (const col of cols) {
+				const av = a[col];
+				const bv = b[col];
+				if (av === bv) continue;
+				if (av == null) return -1;
+				if (bv == null) return 1;
+				if (typeof av === "number" && typeof bv === "number") return av - bv;
+				const as = String(av);
+				const bs = String(bv);
+				if (as !== bs) return as < bs ? -1 : 1;
+			}
+			return 0;
+		});
+	}
+	return {
+		guard,
+		dedupe,
+		sort
+	};
+}
+function defineIcebergDataset(def) {
+	const tableSpec = deriveTableSpec(def);
+	const schema = icebergSchemaFromSpec(tableSpec);
+	const partitionSpecIcebird = icebergPartitionSpecFromSpec(tableSpec);
+	const sortOrder = icebergSortOrderFromSpec(tableSpec);
+	const { guard, dedupe, sort } = buildRowProcessor(def, tableSpec);
+	async function createTable(conn) {
+		const results = [];
+		await icebergCreateTable({
+			catalog: conn.catalog,
+			namespace: conn.namespace,
+			table: def.table,
+			schema,
+			partitionSpec: partitionSpecIcebird,
+			...sortOrder ? { sortOrder } : {}
+		}).then(() => results.push({
+			table: def.table,
+			ok: true
+		}), (e) => results.push({
+			table: def.table,
+			ok: false,
+			error: e instanceof Error ? e.message : String(e)
+		}));
+		return results;
+	}
+	function process(rows) {
+		const guarded = [];
+		let skipped = 0;
+		for (const row of rows) {
+			const rec = guard(row);
+			if (rec === null) skipped++;
+			else guarded.push(rec);
+		}
+		return {
+			records: sort(dedupe(guarded)),
+			skipped
+		};
+	}
+	async function appendRows(conn, rows, opts = {}) {
+		if (rows.length === 0) return {
+			accepted: 0,
+			skipped: 0
+		};
+		const { records, skipped } = process(rows);
+		if (records.length === 0) return {
+			accepted: 0,
+			skipped
+		};
+		await icebergAppendRetrying({
+			catalog: conn.catalog,
+			namespace: conn.namespace,
+			table: def.table,
+			resolver: conn.resolver,
+			records
+		}, opts.commitRetry);
+		return {
+			accepted: records.length,
+			skipped
+		};
+	}
+	function appendSink(opts) {
+		let buffer = [];
+		let connection;
+		function connect() {
+			connection ??= connectIcebergCatalog(opts.catalog, opts.connect).then(async (conn) => {
+				await ensureIcebergNamespace(conn);
+				return conn;
+			});
+			return connection;
+		}
+		return {
+			emit(rows) {
+				for (const r of rows) buffer.push(r);
+			},
+			async close() {
+				if (buffer.length === 0) return {
+					flushed: false,
+					accepted: 0,
+					skipped: 0
+				};
+				const rows = buffer;
+				buffer = [];
+				try {
+					const result = await appendRows(await connect(), rows, { commitRetry: opts.commitRetry });
+					if (result.accepted > 0 && opts.ledger) await opts.ledger.record();
+					return {
+						flushed: result.accepted > 0,
+						...result
+					};
+				} catch (error) {
+					return {
+						flushed: false,
+						accepted: 0,
+						skipped: 0,
+						error
+					};
+				}
+			}
+		};
+	}
+	function readerPredicate(identity, dims) {
+		const idNames = identityColumnNames(def.identity);
+		const idEncodings = identityEncodings(def.identity);
+		const matches = idNames.map((name) => ({
+			field: name,
+			value: idEncodings.get(name) === "int32" ? Number(identity) : identity,
+			encoding: idEncodings.get(name) === "int32" ? "int32" : "string"
+		}));
+		if (def.dims && dims) {
+			for (const [name, dim] of Object.entries(def.dims)) if (name in dims) matches.push({
+				field: name,
+				value: dim.toPartitionValue(dims[name]),
+				encoding: dim.boundEncoding
+			});
+		}
+		return matches;
+	}
+	function partitionBoundFilter(identity, months, dims) {
+		return buildManifestPartitionFilter(def.partition, readerPredicate(identity, dims), months);
+	}
+	async function resolveDataFiles(conn, identity, range, dims, opts = {}) {
+		return resolveIcebergDataFiles(conn, {
+			namespace: def.namespace,
+			table: def.table,
+			partitionSpec: def.partition,
+			matches: readerPredicate(identity, dims),
+			range,
+			cache: opts.cache,
+			clock: opts.clock,
+			profiler: opts.profiler
+		});
+	}
+	return {
+		def,
+		tableSpec,
+		icebergSchema: () => schema,
+		icebergPartitionSpec: () => partitionSpecIcebird,
+		icebergSortOrder: () => sortOrder,
+		createTable,
+		appendRows,
+		prepareRows: process,
+		appendSink,
+		readerPredicate,
+		partitionBoundFilter,
+		resolveDataFiles
+	};
+}
+function resolvePyIcebergPython(override) {
+	return override ?? process.env["GSCDUMP_ICEBERG_PYTHON"] ?? "python3";
+}
+async function runPyIcebergWriter(options) {
+	const { execFile } = await import("node:child_process");
+	return new Promise((resolve, reject) => {
+		execFile(options.python, [options.script], { maxBuffer: 64 * 1024 * 1024 }, (err, stdout, stderr) => {
+			let parsed;
+			if (stdout.trim()) try {
+				parsed = JSON.parse(stdout);
+			} catch {}
+			if (parsed && !(err && options.rejectOnProcessError)) {
+				resolve(parsed);
+				return;
+			}
+			if (err) {
+				if (options.processErrorAsParseFailure) {
+					reject(/* @__PURE__ */ new Error(`${options.label} produced no parseable output (${err.message})${stderr ? `: ${stderr}` : ""}`));
+					return;
+				}
+				reject(/* @__PURE__ */ new Error(`${options.label} process failed (${err.message})${stderr ? `: ${stderr}` : ""}`));
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`${options.label} produced no parseable output: ${stdout || stderr}`));
+		}).stdin?.end(JSON.stringify(options.job));
+	});
+}
+const DEFAULT_PARTITION_KEY_ENCODING = "int";
+export { DEFAULT_PARTITION_KEY_ENCODING, ICEBERG_TYPE_MAP, buildManifestPartitionFilter, cacheGet, cachePut, connectIcebergCatalog, defineIcebergDataset, deriveTableSpec, dropIcebergTables, ensureIcebergNamespace, listIcebergTables, resolveIcebergDataFiles, resolvePyIcebergPython, runPyIcebergWriter, toIcebergDayCount };

package/dist/provisioning/index.d.mts

@@ -0,0 +1,124 @@
+import { PartitionKeyEncoding } from "../_chunks/schema.mjs";
+/**
+ * Team-scoped Catalog Site Id allocator (ADR-0021 amendment 11).
+ *
+ * A "Catalog Site Id" is the small INT32 join key every dataset's `'site-int'`
+ * identity partitions on (nuxtseo ADR-0091's `gscdumpSiteIntId` / gscdump's
+ * `user_sites.int_id`). One allocator, owned here, so no consumer hand-rolls
+ * its own next-int sequence (the exact copy-paste class ADR-0021 exists to
+ * close). Pure — the caller persists the result; this module has no DB.
+ *
+ * Two entry points into a team's id space:
+ *  - ADOPT a `supplied` id (e.g. gscdump's existing `int_id` for a site that
+ *    predates the allocator) — validated for TEAM-SCOPE uniqueness, never
+ *    silently reassigned.
+ *  - ALLOCATE fresh — next-int strictly above every existing id in the team
+ *    (adopted ids included), so a later allocation can never collide with an
+ *    earlier adoption.
+ */
+type AllocateCatalogSiteIdResult = {
+  _tag: 'allocated';
+  id: number;
+} | {
+  _tag: 'adopted';
+  id: number;
+} | {
+  _tag: 'collision';
+  id: number;
+};
+interface AllocateCatalogSiteIdOptions {
+  /** Every Catalog Site Id already in use for this team (adopted + previously allocated). */
+  existingIds: Iterable<number>;
+  /**
+   * Adopt this id instead of allocating a fresh one (e.g. gscdump's existing
+   * `int_id`). Validated against `existingIds` for team-scope uniqueness —
+   * a collision is returned as a value, never silently resolved.
+   */
+  supplied?: number;
+}
+/**
+ * Adopt `supplied`, or allocate the next unused int strictly above every id
+ * already in `existingIds`. Never mutates the caller's set; never reuses an
+ * id already present.
+ */
+declare function allocateCatalogSiteId(opts: AllocateCatalogSiteIdOptions): AllocateCatalogSiteIdResult;
+interface CloudflareProvisionCreds {
+  accountId: string;
+  /** Account-scoped management API token (bucket CRUD). */
+  apiToken: string;
+  /** R2-Data-Catalog-scoped token (enable / maintenance-configs / credential). */
+  catalogToken: string;
+  /**
+   * A dedicated R2 *Object Read & Write* token the catalog stores for its OWN
+   * maintenance runs. Compaction is configured but INERT without this — a
+   * catalog with `credential_status:absent` reports `enabled` but never
+   * compacts. Optional (best-effort): omitted, maintenance stays configured
+   * but dormant.
+   */
+  compactionCredentialToken?: string;
+}
+interface ProvisionedCatalogRef {
+  catalogUri: string;
+  warehouse: string;
+  bucket: string;
+  namespace: string;
+}
+interface SelfProvisionOptions {
+  creds: CloudflareProvisionCreds;
+  bucket: string;
+  namespace: string;
+  /** Browser-read CORS origins for direct S3 presigned reads (DuckDB-WASM). */
+  corsOrigins: readonly string[];
+  /** Injectable fetch — defaults to the global. */
+  fetch?: typeof fetch;
+  /** Injectable warn sink for best-effort maintenance failures. Defaults to `console.warn`. */
+  onWarn?: (message: string) => void;
+}
+/**
+ * Self-provision (idempotently) a team's R2 bucket + Data Catalog: create the
+ * bucket, set browser-read CORS, enable the catalog, set the maintenance
+ * credential, then enable compaction + snapshot expiry. Every step treats
+ * "already exists/enabled" as success. Table creation is NOT this routine's
+ * job — callers create their own dataset tables via `dataset.createTable`
+ * once the namespace exists.
+ */
+declare function selfProvisionCatalog(opts: SelfProvisionOptions): Promise<ProvisionedCatalogRef>;
+/** A remote catalog ref as reported by a partner's catalog API (gscdump's `/teams/:id/catalog`, e.g.). */
+interface RemoteCatalogRef {
+  catalogUri: string | null;
+  warehouse: string | null;
+  bucket: string | null;
+  namespace?: string | null;
+  keyEncoding?: PartitionKeyEncoding | null;
+  provisioningState?: string | null;
+}
+type AdoptCatalogResult = {
+  _tag: 'adopted';
+  ref: ProvisionedCatalogRef;
+} | {
+  _tag: 'no-catalog';
+} | {
+  _tag: 'rejected';
+  reason: 'not-ready' | 'key-encoding';
+  detail: string;
+};
+interface AdoptCatalogOptions {
+  /** Identity partitions this consumer writes require this encoding (default `'int'`). */
+  requireEncoding?: PartitionKeyEncoding;
+}
+/**
+ * ADOPT mode: validate a partner-reported catalog ref rather than provisioning
+ * a second one. Rejections are deliberate hard gates, not fallbacks:
+ *  - `key-encoding` — writers key identity unconditionally in one encoding;
+ *    adopting a mismatched catalog would poison it (partition type mismatch).
+ *  - `not-ready` — the partner owns that catalog's lifecycle; provisioning a
+ *    parallel one would fork the team's lake.
+ */
+declare function adoptCatalog(remote: RemoteCatalogRef | null, opts?: AdoptCatalogOptions): AdoptCatalogResult;
+/**
+ * SUPPLIED-CATALOG mode: an external caller hands in R2 details directly
+ * ("provision a gscdump account with the R2 details and it just works") — a
+ * pure validation/passthrough, no CF calls, no persistence.
+ */
+declare function suppliedCatalog(ref: ProvisionedCatalogRef): ProvisionedCatalogRef;
+export { AdoptCatalogOptions, AdoptCatalogResult, type AllocateCatalogSiteIdOptions, type AllocateCatalogSiteIdResult, CloudflareProvisionCreds, ProvisionedCatalogRef, RemoteCatalogRef, SelfProvisionOptions, adoptCatalog, allocateCatalogSiteId, selfProvisionCatalog, suppliedCatalog };

package/dist/provisioning/index.mjs

@@ -0,0 +1,141 @@
+const INT32_MAX = 2147483647;
+function allocateCatalogSiteId(opts) {
+	const existing = new Set(opts.existingIds);
+	if (opts.supplied != null) {
+		if (existing.has(opts.supplied)) return {
+			_tag: "collision",
+			id: opts.supplied
+		};
+		return {
+			_tag: "adopted",
+			id: opts.supplied
+		};
+	}
+	let max = 0;
+	for (const id of existing) if (id > max) max = id;
+	let next = max + 1;
+	while (existing.has(next)) next++;
+	if (next > INT32_MAX) throw new RangeError(`allocateCatalogSiteId: exhausted the INT32 id space (next=${next})`);
+	return {
+		_tag: "allocated",
+		id: next
+	};
+}
+const CF_API_BASE = "https://api.cloudflare.com/client/v4";
+const COMPACTION_TARGET_SIZE_MB = "128";
+const SNAPSHOT_MIN_SNAPSHOTS_TO_KEEP = 10;
+const SNAPSHOT_MAX_AGE = "3d";
+function isBenignConflict(status, body) {
+	if (status === 409) return true;
+	const lower = body.toLowerCase();
+	return lower.includes("already exist") || lower.includes("already enabled") || lower.includes("already in use");
+}
+async function cfPost(fetchImpl, accountId, token, path, body) {
+	const res = await fetchImpl(`${CF_API_BASE}/accounts/${accountId}/${path}`, {
+		method: "POST",
+		headers: {
+			"Authorization": `Bearer ${token}`,
+			"Content-Type": "application/json"
+		},
+		body: body === void 0 ? void 0 : JSON.stringify(body)
+	});
+	const text = await res.text();
+	if (res.ok) {
+		const json = text ? JSON.parse(text) : { success: true };
+		if (json.success === false && !isBenignConflict(res.status, text)) throw new Error(`CF POST ${path} failed: ${json.errors?.map((e) => e.message).join(", ") || text}`);
+		return;
+	}
+	if (isBenignConflict(res.status, text)) return;
+	throw new Error(`CF POST ${path} failed: ${res.status} ${text}`);
+}
+async function putBucketCors(fetchImpl, accountId, apiToken, bucket, origins) {
+	const res = await fetchImpl(`${CF_API_BASE}/accounts/${accountId}/r2/buckets/${bucket}/cors`, {
+		method: "PUT",
+		headers: {
+			"Authorization": `Bearer ${apiToken}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({ rules: [{
+			allowed: {
+				origins,
+				methods: ["GET", "HEAD"],
+				headers: ["range", "content-type"]
+			},
+			exposeHeaders: [
+				"content-range",
+				"content-length",
+				"accept-ranges",
+				"etag"
+			],
+			maxAgeSeconds: 86400
+		}] })
+	});
+	if (res.ok) return;
+	const text = await res.text().catch(() => "");
+	if (isBenignConflict(res.status, text)) return;
+	throw new Error(`CF PUT /r2/buckets/${bucket}/cors failed: ${res.status} ${text}`);
+}
+async function enableMaintenance(fetchImpl, accountId, catalogToken, bucket, onWarn) {
+	await cfPost(fetchImpl, accountId, catalogToken, `r2-catalog/${bucket}/maintenance-configs`, {
+		compaction: {
+			state: "enabled",
+			target_size_mb: COMPACTION_TARGET_SIZE_MB
+		},
+		snapshot_expiration: {
+			state: "enabled",
+			min_snapshots_to_keep: SNAPSHOT_MIN_SNAPSHOTS_TO_KEEP,
+			max_snapshot_age: SNAPSHOT_MAX_AGE
+		}
+	}).catch((err) => {
+		onWarn(`[lakehouse-provisioning] maintenance-configs failed for ${bucket} — catalog usable but maintenance stays off: ${err instanceof Error ? err.message : String(err)}`);
+	});
+}
+async function ensureCredential(fetchImpl, accountId, catalogToken, credentialToken, bucket, onWarn) {
+	await cfPost(fetchImpl, accountId, catalogToken, `r2-catalog/${bucket}/credential`, { token: credentialToken }).catch((err) => {
+		onWarn(`[lakehouse-provisioning] credential-set failed for ${bucket} — compaction stays inert (credential absent): ${err instanceof Error ? err.message : String(err)}`);
+	});
+}
+async function selfProvisionCatalog(opts) {
+	const { creds, bucket, namespace, corsOrigins } = opts;
+	const fetchImpl = opts.fetch ?? fetch;
+	const onWarn = opts.onWarn ?? ((m) => console.warn(m));
+	await cfPost(fetchImpl, creds.accountId, creds.apiToken, "r2/buckets", { name: bucket });
+	await putBucketCors(fetchImpl, creds.accountId, creds.apiToken, bucket, corsOrigins);
+	await cfPost(fetchImpl, creds.accountId, creds.catalogToken, `r2-catalog/${bucket}/enable`, {});
+	if (creds.compactionCredentialToken) await ensureCredential(fetchImpl, creds.accountId, creds.catalogToken, creds.compactionCredentialToken, bucket, onWarn);
+	await enableMaintenance(fetchImpl, creds.accountId, creds.catalogToken, bucket, onWarn);
+	return {
+		catalogUri: `https://catalog.cloudflarestorage.com/${creds.accountId}/${bucket}`,
+		warehouse: `${creds.accountId}_${bucket}`,
+		bucket,
+		namespace
+	};
+}
+function adoptCatalog(remote, opts = {}) {
+	if (!remote || !remote.catalogUri || !remote.warehouse || !remote.bucket) return { _tag: "no-catalog" };
+	const requireEncoding = opts.requireEncoding ?? "int";
+	if (remote.keyEncoding && remote.keyEncoding !== requireEncoding) return {
+		_tag: "rejected",
+		reason: "key-encoding",
+		detail: `catalog is ${remote.keyEncoding}-encoded; writers require ${requireEncoding}`
+	};
+	if (remote.provisioningState && remote.provisioningState !== "ready") return {
+		_tag: "rejected",
+		reason: "not-ready",
+		detail: `provisioningState=${remote.provisioningState}`
+	};
+	return {
+		_tag: "adopted",
+		ref: {
+			catalogUri: remote.catalogUri,
+			warehouse: remote.warehouse,
+			bucket: remote.bucket,
+			namespace: remote.namespace ?? "default"
+		}
+	};
+}
+function suppliedCatalog(ref) {
+	if (!ref.catalogUri || !ref.warehouse || !ref.bucket) throw new Error("suppliedCatalog: catalogUri, warehouse and bucket are all required");
+	return ref;
+}
+export { adoptCatalog, allocateCatalogSiteId, selfProvisionCatalog, suppliedCatalog };

package/dist/unsafe-raw.d.mts

@@ -0,0 +1,3 @@
+import { icebergAppendRetrying, isCommitRateLimited } from "./_chunks/catalog.mjs";
+import { icebergAppend, icebergCreateTable, icebergDropTable, icebergManifests, restCatalogConnect, restCatalogCreateNamespace, restCatalogListTables, restCatalogLoadTable, s3SignedResolver } from "./_chunks/libs/icebird.mjs";
+export { icebergAppend, icebergAppendRetrying, icebergCreateTable, icebergDropTable, icebergManifests, isCommitRateLimited, restCatalogConnect, restCatalogCreateNamespace, restCatalogListTables, restCatalogLoadTable, s3SignedResolver };

package/dist/unsafe-raw.mjs

@@ -0,0 +1,3 @@
+import { icebergAppend, icebergCreateTable, icebergDropTable, icebergManifests, restCatalogConnect, restCatalogCreateNamespace, restCatalogListTables, restCatalogLoadTable, s3SignedResolver } from "./_chunks/libs/icebird.mjs";
+import { icebergAppendRetrying, isCommitRateLimited } from "./_chunks/catalog.mjs";
+export { icebergAppend, icebergAppendRetrying, icebergCreateTable, icebergDropTable, icebergManifests, isCommitRateLimited, restCatalogConnect, restCatalogCreateNamespace, restCatalogListTables, restCatalogLoadTable, s3SignedResolver };

package/dist/vendor/hysnappy-purejs.d.mts

@@ -0,0 +1,29 @@
+/**
+ * Pure-JS drop-in replacement for `hysnappy`.
+ *
+ * `hysnappy`'s `snappyUncompressor()` eagerly compiles a WASM module
+ * (`new WebAssembly.Module(byteArray)`) — and `hyparquet-compressors`
+ * instantiates it at module top level (`SNAPPY: snappyUncompressor()`).
+ * Cloudflare's `workerd` forbids compiling WebAssembly from a runtime buffer
+ * (WASM must be a bundled module import), so any Worker bundle that imports
+ * `icebird` (→ `hyparquet-compressors`) fails to start with
+ * `CompileError: Wasm code generation disallowed by embedder`.
+ *
+ * `icebird`'s append path never actually decompresses a snappy data file — it
+ * only reads gzipped `metadata.json` and Avro manifests — so the snappy
+ * decompressor is instantiated but never invoked. This shim swaps the WASM
+ * codec for `hyparquet`'s pure-JS snappy decompressor (a vendored snappyjs),
+ * keeping the exact `hysnappy` API surface so `hyparquet-compressors` is
+ * unaware of the swap. Wired in via a build-time `hysnappy` alias.
+ *
+ * See `docs/plans/2026-05-22-icebird-ingest-writer-spike.md` (section e).
+ */
+/**
+ * Pure-JS stand-in for `hysnappy`'s `snappyUncompressor()`. Returns the
+ * decompressor immediately — no WASM compilation, so it is safe to call at
+ * module top level inside `workerd`.
+ */
+declare function snappyUncompressor(): (input: Uint8Array, outputLength: number) => Uint8Array;
+/** Pure-JS stand-in for `hysnappy`'s `snappyUncompress(input, outputLength)`. */
+declare function snappyUncompress(input: Uint8Array, outputLength: number): Uint8Array;
+export { snappyUncompress, snappyUncompressor };

package/dist/vendor/hysnappy-purejs.mjs

@@ -0,0 +1,2 @@
+import { snappyUncompress, snappyUncompressor } from "../_chunks/libs/hyparquet-compressors.mjs";
+export { snappyUncompress, snappyUncompressor };