@gscdump/engine 0.4.0

package/dist/adapters/r2-manifest.d.mts

@@ -0,0 +1,227 @@
+import { TableName, TableName as TableName$1 } from "gscdump/contracts";
+import { SearchType } from "gscdump/query";
+/**
+ * Compaction tier of a manifest entry. Determines which compactor stage may
+ * pick it up as input:
+ * - `raw`: per-day file produced by `writeDay`. Eligible for raw→d7 merge at 7d.
+ * - `d7`: weekly compaction output. Eligible for d7→d30 merge at 30d.
+ * - `d30`: monthly compaction output (matches the legacy `monthly/` partition
+ *   shape — pre-tier entries are read as `d30`). Eligible for d30→d90 at 90d.
+ * - `d90`: quarterly cold-tier output. Terminal; never recompacted.
+ *
+ * Without an explicit tier, entries written before this field landed default
+ * to `raw` for `daily/` partitions and `d30` for `monthly/` partitions, so
+ * the tiered compactor picks the right inputs without a backfill rewrite.
+ */
+type CompactionTier = 'raw' | 'd7' | 'd30' | 'd90';
+interface ManifestEntry {
+  userId: string;
+  siteId?: string;
+  table: TableName;
+  partition: string;
+  objectKey: string;
+  rowCount: number;
+  bytes: number;
+  createdAt: number;
+  retiredAt?: number;
+  /** Table schema version at write time. Omitted on pre-#27 entries — treat as 1. */
+  schemaVersion?: number;
+  /**
+   * Compaction tier. Omitted on entries written before tiered compaction —
+   * treat as `raw` for `daily/` partitions and `d30` for `monthly/` partitions
+   * (see {@link inferLegacyTier}).
+   */
+  tier?: CompactionTier;
+  /**
+   * GSC search-type this entry covers (web | discover | news | googleNews |
+   * image | video). Omitted on entries written before per-type partitioning
+   * landed — treat as `web` (see {@link inferSearchType}). Compaction merges
+   * only entries with the same searchType.
+   */
+  searchType?: SearchType;
+}
+interface ListLiveFilter {
+  userId: string;
+  siteId?: string;
+  table?: TableName;
+  partitions?: string[];
+  /**
+   * Narrow to a single compaction tier. Tier-aware compaction stages set this
+   * so the store doesn't have to return (and the caller doesn't have to scan)
+   * the entire manifest just to compact the raw cohort. Legacy entries without
+   * an explicit `tier` field match on {@link inferLegacyTier}.
+   */
+  tier?: CompactionTier;
+}
+interface WatermarkScope {
+  userId: string;
+  siteId?: string;
+  table: TableName;
+}
+interface Watermark extends WatermarkScope {
+  newestDateSynced: string;
+  oldestDateSynced: string;
+  lastSyncAt: number;
+}
+interface WatermarkFilter {
+  userId: string;
+  siteId?: string;
+  table?: TableName;
+}
+type SyncStateKind = 'pending' | 'inflight' | 'done' | 'failed';
+interface SyncStateScope {
+  userId: string;
+  siteId?: string;
+  table: TableName;
+  date: string;
+  /**
+   * GSC search-type this sync state covers. Omitted = `web` (the legacy
+   * default; matches pre-#5 sync states stored before per-type sync landed).
+   * Lookups must compare via {@link inferSearchType} so a missing field
+   * matches an explicit `'web'` and vice versa.
+   */
+  searchType?: SearchType;
+}
+interface SyncState extends SyncStateScope {
+  state: SyncStateKind;
+  updatedAt: number;
+  attempts: number;
+  error?: string;
+}
+interface SyncStateFilter {
+  userId: string;
+  siteId?: string;
+  table?: TableName;
+  state?: SyncStateKind;
+  searchType?: SearchType;
+}
+interface SyncStateDetail {
+  at?: number;
+  error?: string;
+}
+interface LockScope {
+  userId: string;
+  siteId?: string;
+  table: TableName;
+  partition: string;
+}
+interface PurgeFilter {
+  userId: string;
+  siteId?: string;
+}
+interface ManifestPurgeResult {
+  entriesRemoved: number;
+  watermarksRemoved: number;
+  syncStatesRemoved: number;
+}
+interface ManifestStore {
+  listLive: (filter: ListLiveFilter) => Promise<ManifestEntry[]>;
+  listAll: (filter: ListLiveFilter) => Promise<ManifestEntry[]>;
+  registerVersion: (entry: ManifestEntry, superseding?: ManifestEntry[]) => Promise<void>;
+  registerVersions: (entries: ManifestEntry[], superseding?: ManifestEntry[]) => Promise<void>;
+  listRetired: (olderThan: number) => Promise<ManifestEntry[]>;
+  delete: (entries: ManifestEntry[]) => Promise<void>;
+  getWatermarks: (filter: WatermarkFilter) => Promise<Watermark[]>;
+  bumpWatermark: (scope: WatermarkScope, date: string, at?: number) => Promise<void>;
+  getSyncStates: (filter: SyncStateFilter) => Promise<SyncState[]>;
+  setSyncState: (scope: SyncStateScope, state: SyncStateKind, detail?: SyncStateDetail) => Promise<void>;
+  /**
+   * Serialize concurrent writers against the same scope. Held across the
+   * write+register window so GC (orphan sweep) won't delete bytes that are
+   * midway between `dataSource.write` and `manifestStore.registerVersion`.
+   * Scope = tenant × table × partition.
+   */
+  withLock: <T>(scope: LockScope, fn: () => Promise<T>) => Promise<T>;
+  /**
+   * GDPR-grade tenant purge. Removes every manifest entry, watermark, and
+   * sync-state record matching the filter. Does NOT touch the underlying
+   * data-source bytes; callers (typically {@link StorageEngine.purgeTenant})
+   * must sweep the tenant prefix separately before invoking this so that
+   * mid-flight failures can't leave orphan parquet with no manifest record.
+   *
+   * On stores with CAS-backed sharding (R2 manifest) this may issue one
+   * mutation per shard. On read-only stores (HTTP) this throws.
+   */
+  purgeTenant: (filter: PurgeFilter) => Promise<ManifestPurgeResult>;
+}
+interface R2ObjectMetadata {
+  etag: string;
+}
+interface R2ObjectBody extends R2ObjectMetadata {
+  text: () => Promise<string>;
+}
+interface R2ListResult {
+  objects: Array<{
+    key: string;
+  }>;
+  truncated: boolean;
+  cursor?: string;
+}
+interface R2ConditionalPutOptions {
+  /**
+   * Workers-binding-style precondition. `etagMatches` rejects with `null`
+   *  return on mismatch; `etagDoesNotMatch: '*'` rejects if the key exists.
+   */
+  onlyIf?: {
+    etagMatches?: string;
+    etagDoesNotMatch?: string;
+  };
+}
+/**
+ * Minimal Cloudflare R2 binding shape needed for the manifest CAS loop.
+ * Structurally compatible with Cloudflare's `R2Bucket` Workers API.
+ */
+interface R2ManifestBucketLike {
+  get: (key: string) => Promise<R2ObjectBody | null>;
+  put: (key: string, bytes: string | Uint8Array, options?: R2ConditionalPutOptions) => Promise<R2ObjectMetadata | null>;
+  list: (options?: {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+  }) => Promise<R2ListResult>;
+  /**
+   * Bulk delete. Required by {@link ManifestStore.purgeTenant}. Cloudflare's
+   * `R2Bucket.delete` accepts a single key or a string[] batch; both shapes
+   * work here.
+   */
+  delete: (keys: string | string[]) => Promise<void>;
+}
+/**
+ * CAS lifecycle events emitted by the manifest store. Consumers wire these
+ * into metrics (prom-client, console.table, the contention harness) to
+ * measure rejection rate and latency under real R2 load.
+ */
+type R2ManifestEvent = {
+  kind: 'cas-attempt';
+  siteId: string;
+  table: TableName$1;
+  attempt: number;
+} | {
+  kind: 'cas-rejected';
+  siteId: string;
+  table: TableName$1;
+  attempt: number;
+} | {
+  kind: 'cas-committed';
+  siteId: string;
+  table: TableName$1;
+  attempts: number;
+};
+interface CreateR2ManifestStoreOptions {
+  bucket: R2ManifestBucketLike;
+  /** Tenant scope. All shard keys are prefixed `u_<userId>/manifest/...`. */
+  userId: string;
+  /** Override the snapshot version-id generator. Defaults to `${ts}-${random}`. */
+  newSnapshotId?: () => string;
+  now?: () => number;
+  /** Maximum CAS retries before giving up. Defaults to 8. */
+  maxRetries?: number;
+  /**
+   * Optional telemetry hook. Fired synchronously from the CAS loop on each
+   * attempt, rejection, and successful commit. Must not throw; exceptions
+   * propagate and will fail the mutation.
+   */
+  onEvent?: (event: R2ManifestEvent) => void;
+}
+declare function createR2ManifestStore(opts: CreateR2ManifestStoreOptions): ManifestStore;
+export { CreateR2ManifestStoreOptions, R2ManifestBucketLike, R2ManifestEvent, createR2ManifestStore };

package/dist/adapters/r2-manifest.mjs

@@ -0,0 +1,355 @@
+function inferSearchType(entry) {
+	return entry.searchType ?? "web";
+}
+function inferLegacyTier(entry) {
+	if (entry.tier !== void 0) return entry.tier;
+	if (entry.partition.startsWith("daily/")) return "raw";
+	if (entry.partition.startsWith("monthly/")) return "d30";
+}
+const SHARD_RE = /^u_[^/]+\/manifest\/(?<siteId>[^/]+)\/(?<table>[^/]+)\/HEAD$/;
+function defaultSnapshotId() {
+	return `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function shardPrefix(userId, siteId, table) {
+	return `u_${userId}/manifest/${siteId}/${table}/`;
+}
+function headKey(userId, siteId, table) {
+	return `${shardPrefix(userId, siteId, table)}HEAD`;
+}
+function snapshotKey(userId, siteId, table, snapshotId) {
+	return `${shardPrefix(userId, siteId, table)}v${snapshotId}.json`;
+}
+function emptySnapshot() {
+	return {
+		version: 1,
+		entries: [],
+		watermarks: [],
+		syncStates: []
+	};
+}
+function shardScopesFromEntries(entries) {
+	const out = /* @__PURE__ */ new Set();
+	for (const e of entries) {
+		if (e.siteId === void 0) throw new Error("R2 manifest store requires entries to carry siteId; cross-site entries are unshardable");
+		out.add(`${e.siteId}\0${e.table}`);
+	}
+	return out;
+}
+function matchesEntryFilter(entry, filter) {
+	if (filter.siteId !== void 0 && entry.siteId !== filter.siteId) return false;
+	if (filter.table !== void 0 && entry.table !== filter.table) return false;
+	if (filter.partitions && !filter.partitions.includes(entry.partition)) return false;
+	if (filter.tier !== void 0 && inferLegacyTier(entry) !== filter.tier) return false;
+	return true;
+}
+function matchesWatermarkFilter(w, filter) {
+	if (filter.siteId !== void 0 && w.siteId !== filter.siteId) return false;
+	if (filter.table !== void 0 && w.table !== filter.table) return false;
+	return true;
+}
+function matchesSyncStateFilter(s, filter) {
+	if (filter.siteId !== void 0 && s.siteId !== filter.siteId) return false;
+	if (filter.table !== void 0 && s.table !== filter.table) return false;
+	if (filter.state !== void 0 && s.state !== filter.state) return false;
+	if (filter.searchType !== void 0 && inferSearchType(s) !== filter.searchType) return false;
+	return true;
+}
+function createR2ManifestStore(opts) {
+	const { bucket, userId } = opts;
+	const newSnapshotId = opts.newSnapshotId ?? defaultSnapshotId;
+	const now = opts.now ?? (() => Date.now());
+	const maxRetries = opts.maxRetries ?? 8;
+	const onEvent = opts.onEvent;
+	async function readShard(siteId, table) {
+		const head = await bucket.get(headKey(userId, siteId, table));
+		if (!head) return {
+			snapshot: emptySnapshot(),
+			headEtag: void 0
+		};
+		const snapshotId = (await head.text()).trim();
+		if (!snapshotId) return {
+			snapshot: emptySnapshot(),
+			headEtag: head.etag
+		};
+		const snap = await bucket.get(snapshotKey(userId, siteId, table, snapshotId));
+		if (!snap) return {
+			snapshot: emptySnapshot(),
+			headEtag: head.etag
+		};
+		const parsed = JSON.parse(await snap.text());
+		if (parsed.version !== 1) throw new Error(`unsupported manifest snapshot version: ${parsed.version}`);
+		return {
+			snapshot: parsed,
+			headEtag: head.etag
+		};
+	}
+	async function writeShard(siteId, table, snapshot, headEtag) {
+		const id = newSnapshotId();
+		const snapKey = snapshotKey(userId, siteId, table, id);
+		await bucket.put(snapKey, JSON.stringify(snapshot));
+		const conditional = headEtag ? { onlyIf: { etagMatches: headEtag } } : { onlyIf: { etagDoesNotMatch: "*" } };
+		return { ok: await bucket.put(headKey(userId, siteId, table), id, conditional) !== null };
+	}
+	async function mutateShard(siteId, table, mutate) {
+		let attempt = 0;
+		while (attempt < maxRetries) {
+			onEvent?.({
+				kind: "cas-attempt",
+				siteId,
+				table,
+				attempt
+			});
+			const { snapshot, headEtag } = await readShard(siteId, table);
+			await mutate(snapshot);
+			const { ok } = await writeShard(siteId, table, snapshot, headEtag);
+			if (ok) {
+				onEvent?.({
+					kind: "cas-committed",
+					siteId,
+					table,
+					attempts: attempt + 1
+				});
+				return;
+			}
+			onEvent?.({
+				kind: "cas-rejected",
+				siteId,
+				table,
+				attempt
+			});
+			attempt++;
+		}
+		throw new Error(`R2 manifest CAS exceeded ${maxRetries} retries for ${siteId}/${table}`);
+	}
+	async function listShards() {
+		const shards = [];
+		let cursor;
+		do {
+			const res = await bucket.list({
+				prefix: `u_${userId}/manifest/`,
+				cursor,
+				limit: 1e3
+			});
+			for (const obj of res.objects) {
+				const m = SHARD_RE.exec(obj.key);
+				if (m?.groups) shards.push({
+					siteId: m.groups.siteId,
+					table: m.groups.table
+				});
+			}
+			cursor = res.truncated ? res.cursor : void 0;
+		} while (cursor);
+		return shards;
+	}
+	async function shardsForFilter(filter) {
+		if (filter.siteId !== void 0 && filter.table !== void 0) return [{
+			siteId: filter.siteId,
+			table: filter.table
+		}];
+		return (await listShards()).filter((s) => (filter.siteId === void 0 || s.siteId === filter.siteId) && (filter.table === void 0 || s.table === filter.table));
+	}
+	async function readEntriesAcrossShards(filter, includeRetired) {
+		const shards = await shardsForFilter(filter);
+		const all = [];
+		for (const { siteId, table } of shards) {
+			const { snapshot } = await readShard(siteId, table);
+			for (const entry of snapshot.entries) {
+				if (!includeRetired && entry.retiredAt !== void 0) continue;
+				if (matchesEntryFilter(entry, filter)) all.push(entry);
+			}
+		}
+		return all;
+	}
+	function groupBySiteTable(entries) {
+		const out = /* @__PURE__ */ new Map();
+		for (const e of entries) {
+			const key = `${e.siteId}\0${e.table}`;
+			if (!out.has(key)) out.set(key, []);
+			out.get(key).push(e);
+		}
+		return out;
+	}
+	async function registerVersionsImpl(newEntries, superseding) {
+		if (newEntries.length === 0 && (!superseding || superseding.length === 0)) return;
+		const supersededAt = newEntries[0]?.createdAt ?? now();
+		const byShard = /* @__PURE__ */ new Map();
+		function bucket(entry, kind) {
+			if (entry.siteId === void 0) throw new Error("R2 manifest store requires entries to carry siteId");
+			const key = `${entry.siteId}\0${entry.table}`;
+			let bag = byShard.get(key);
+			if (!bag) {
+				bag = {
+					newEntries: [],
+					superseding: []
+				};
+				byShard.set(key, bag);
+			}
+			if (kind === "new") bag.newEntries.push(entry);
+			else bag.superseding.push(entry);
+		}
+		for (const e of newEntries) bucket(e, "new");
+		if (superseding) for (const e of superseding) bucket(e, "super");
+		for (const [shardKey, { newEntries: news, superseding: supers }] of byShard) {
+			const [siteId, table] = shardKey.split("\0");
+			await mutateShard(siteId, table, (snap) => {
+				const byObjectKey = new Map(snap.entries.map((e) => [e.objectKey, e]));
+				for (const s of supers) {
+					const existing = byObjectKey.get(s.objectKey);
+					if (existing && existing.retiredAt === void 0) byObjectKey.set(s.objectKey, {
+						...existing,
+						retiredAt: supersededAt
+					});
+				}
+				for (const n of news) byObjectKey.set(n.objectKey, n);
+				snap.entries = Array.from(byObjectKey.values());
+			});
+		}
+	}
+	return {
+		async listLive(filter) {
+			return readEntriesAcrossShards(filter, false);
+		},
+		async listAll(filter) {
+			return readEntriesAcrossShards(filter, true);
+		},
+		async registerVersion(entry, superseding) {
+			return registerVersionsImpl([entry], superseding);
+		},
+		async registerVersions(entries, superseding) {
+			shardScopesFromEntries(entries);
+			return registerVersionsImpl(entries, superseding);
+		},
+		async listRetired(olderThan) {
+			const shards = await listShards();
+			const out = [];
+			for (const { siteId, table } of shards) {
+				const { snapshot } = await readShard(siteId, table);
+				for (const e of snapshot.entries) if (e.retiredAt !== void 0 && e.retiredAt <= olderThan) out.push(e);
+			}
+			return out;
+		},
+		async delete(toDelete) {
+			const grouped = groupBySiteTable(toDelete);
+			for (const [shardKey, entries] of grouped) {
+				const [siteId, table] = shardKey.split("\0");
+				await mutateShard(siteId, table, (snap) => {
+					const drop = new Set(entries.map((e) => e.objectKey));
+					snap.entries = snap.entries.filter((e) => !drop.has(e.objectKey));
+				});
+			}
+		},
+		async getWatermarks(filter) {
+			const shards = await shardsForFilter(filter);
+			const out = [];
+			for (const { siteId, table } of shards) {
+				const { snapshot } = await readShard(siteId, table);
+				for (const w of snapshot.watermarks) if (matchesWatermarkFilter(w, filter)) out.push(w);
+			}
+			return out;
+		},
+		async bumpWatermark(scope, date, at) {
+			if (scope.siteId === void 0) throw new Error("R2 manifest store requires watermarks to carry siteId");
+			const ts = at ?? now();
+			await mutateShard(scope.siteId, scope.table, (snap) => {
+				const idx = snap.watermarks.findIndex((w) => w.userId === userId && w.siteId === scope.siteId && w.table === scope.table);
+				if (idx === -1) {
+					snap.watermarks.push({
+						userId,
+						siteId: scope.siteId,
+						table: scope.table,
+						newestDateSynced: date,
+						oldestDateSynced: date,
+						lastSyncAt: ts
+					});
+					return;
+				}
+				const w = snap.watermarks[idx];
+				const newest = date > w.newestDateSynced ? date : w.newestDateSynced;
+				const oldest = date < w.oldestDateSynced ? date : w.oldestDateSynced;
+				const lastSyncAt = ts > w.lastSyncAt ? ts : w.lastSyncAt;
+				snap.watermarks[idx] = {
+					...w,
+					newestDateSynced: newest,
+					oldestDateSynced: oldest,
+					lastSyncAt
+				};
+			});
+		},
+		async getSyncStates(filter) {
+			const shards = await shardsForFilter(filter);
+			const out = [];
+			for (const { siteId, table } of shards) {
+				const { snapshot } = await readShard(siteId, table);
+				for (const s of snapshot.syncStates) if (matchesSyncStateFilter(s, filter)) out.push(s);
+			}
+			return out;
+		},
+		async setSyncState(scope, state, detail) {
+			if (scope.siteId === void 0) throw new Error("R2 manifest store requires sync states to carry siteId");
+			const at = detail?.at ?? now();
+			const scopeSearchType = inferSearchType(scope);
+			await mutateShard(scope.siteId, scope.table, (snap) => {
+				const idx = snap.syncStates.findIndex((s) => s.userId === userId && s.siteId === scope.siteId && s.table === scope.table && s.date === scope.date && inferSearchType(s) === scopeSearchType);
+				if (idx === -1) {
+					snap.syncStates.push({
+						userId,
+						siteId: scope.siteId,
+						table: scope.table,
+						date: scope.date,
+						state,
+						updatedAt: at,
+						attempts: 1,
+						error: detail?.error,
+						...scope.searchType !== void 0 ? { searchType: scope.searchType } : {}
+					});
+					return;
+				}
+				const prev = snap.syncStates[idx];
+				const attempts = state === "inflight" && prev.state !== "inflight" ? prev.attempts + 1 : prev.attempts;
+				const error = state === "done" ? void 0 : detail?.error ?? prev.error;
+				snap.syncStates[idx] = {
+					...prev,
+					state,
+					updatedAt: at,
+					attempts,
+					error
+				};
+			});
+		},
+		async withLock(_scope, fn) {
+			return fn();
+		},
+		async purgeTenant(filter) {
+			if (filter.userId !== userId) throw new Error(`purgeTenant: store is scoped to userId=${userId}, got ${filter.userId}`);
+			const shards = await shardsForFilter({ siteId: filter.siteId });
+			let entriesRemoved = 0;
+			let watermarksRemoved = 0;
+			let syncStatesRemoved = 0;
+			for (const { siteId, table } of shards) {
+				const { snapshot } = await readShard(siteId, table);
+				entriesRemoved += snapshot.entries.length;
+				watermarksRemoved += snapshot.watermarks.length;
+				syncStatesRemoved += snapshot.syncStates.length;
+				const prefix = shardPrefix(userId, siteId, table);
+				const keys = [];
+				let cursor;
+				do {
+					const res = await bucket.list({
+						prefix,
+						cursor,
+						limit: 1e3
+					});
+					for (const obj of res.objects) keys.push(obj.key);
+					cursor = res.truncated ? res.cursor : void 0;
+				} while (cursor);
+				if (keys.length > 0) await bucket.delete(keys);
+			}
+			return {
+				entriesRemoved,
+				watermarksRemoved,
+				syncStatesRemoved
+			};
+		}
+	};
+}
+export { createR2ManifestStore };

package/dist/adapters/r2.d.mts

@@ -0,0 +1,93 @@
+interface DataSource {
+  read: (key: string, range?: {
+    offset: number;
+    length: number;
+  }, signal?: AbortSignal) => Promise<Uint8Array>;
+  write: (key: string, bytes: Uint8Array) => Promise<void>;
+  delete: (keys: string[]) => Promise<void>;
+  /**
+   * One-shot listing under a prefix. Implementations may cap the number of
+   * returned keys (typically 10k) — callers iterating full tenant space
+   * should prefer `streamList` when available or narrow the prefix.
+   */
+  list: (prefix: string) => Promise<string[]>;
+  /**
+   * Per-key URI probe. Returns a URI string DuckDB's `httpfs` (or an
+   * equivalent engine that fetches its own I/O) can read directly, or
+   * `undefined` if the key isn't URI-resolvable on this backend and the
+   * caller must fall back to `read(key)` for the bytes.
+   *
+   * Contracts:
+   * - When defined, the returned URI MUST yield byte-identical content to
+   *   `read(key)`. Callers rely on this for correctness.
+   * - Backends with a native URI for every key (filesystem: absolute path,
+   *   R2 via `httpfs`: signed URL) may always return a string.
+   * - Backends without a native URI shape (in-memory) omit the method or
+   *   return `undefined` per call.
+   * - Mixed-per-query is allowed: some keys in one query may return a URI,
+   *   others may not; the executor branches per key.
+   */
+  uri?: (key: string) => string | undefined;
+  /**
+   * Optional — probe the byte size of a key without reading it. Used by
+   * the engine to fill in `WriteResult.bytes` when a codec reports 0 or
+   * unknown but the file is non-trivial.
+   */
+  head?: (key: string) => Promise<{
+    bytes: number;
+  } | undefined>;
+  /**
+   * Optional streaming variant of `list`. Implementations that page
+   * backing-store results (R2, S3) should implement this and yield keys
+   * lazily. `list` may return up to an adapter-defined cap (typically
+   * 10k keys); callers iterating full tenant space must prefer
+   * `streamList` when available, or chunk by narrower prefixes.
+   */
+  streamList?: (prefix: string) => AsyncIterable<string>;
+}
+interface R2GetOptions {
+  range?: {
+    offset: number;
+    length: number;
+  };
+}
+interface R2ObjectBody {
+  arrayBuffer: () => Promise<ArrayBuffer>;
+}
+interface R2HeadObject {
+  size: number;
+}
+interface R2ListResult {
+  objects: Array<{
+    key: string;
+  }>;
+  truncated: boolean;
+  cursor?: string;
+}
+interface R2ListOptions {
+  prefix?: string;
+  cursor?: string;
+  limit?: number;
+}
+interface R2BucketLike {
+  get: (key: string, options?: R2GetOptions) => Promise<R2ObjectBody | null>;
+  put: (key: string, bytes: Uint8Array) => Promise<unknown>;
+  delete: (keys: string | string[]) => Promise<void>;
+  list: (options?: R2ListOptions) => Promise<R2ListResult>;
+  head: (key: string) => Promise<R2HeadObject | null>;
+}
+interface R2DataSourceOptions {
+  /**
+   * R2 bucket binding. Structurally typed — pass a Cloudflare `R2Bucket` or
+   * any object with the same get/put/delete/list/head surface.
+   */
+  bucket: R2BucketLike;
+  /**
+   * When set, `uri(key)` returns `r2://{bucketName}/{key}` for DuckDB httpfs
+   * reads. Omit if the backing DuckDB can't resolve `r2://` URIs and the
+   * caller should fall back to `read(key)` for bytes.
+   */
+  bucketName?: string;
+}
+declare function createR2DataSource(options: R2DataSourceOptions): DataSource;
+export { R2DataSourceOptions, createR2DataSource };