better-supabase 0.5.0 → 0.6.0

package/dist/storage/index.js

@@ -1,31 +1,717 @@
-import { n as dbError, o as isDbError, t as DbException } from "../errors-DtwXa6b8.js";
-import { r as optionalTemporal } from "../temporal-CVlIV2DZ.js";
-import { n as temporalMissing } from "../temporal-required-CAt4Dc9Z.js";
-import { i as ok, n as err, o as toDbError, t as AsyncResult } from "../result-BKiliPY7.js";
-import { o as spansAllTenants, s as tenantOf } from "../plugin-DwARMuQp.js";
-import { i as tenantClaimPaths, n as claimAt } from "../claims-BAf6c7is.js";
-import { i as sqlString, n as slug, r as sqlIdent, t as parseTemplate } from "../template-TxrGI5jR.js";
-import { n as permdockCheck } from "../permdock-sql-DgOfeixi.js";
+import { t as DbException } from "../db-exception-CnWcYPxL.js";
+import { n as dbError } from "../errors-B11Duf73.js";
+import { c as optionalTemporal } from "../temporal-BJGitm-h.js";
+import { n as temporalMissing } from "../temporal-required-BVvW7SYJ.js";
+import { a as ok, r as err, s as toDbError, t as AsyncResult } from "../result-DzUbqgdW.js";
+import { a as spansAllTenants } from "../plugin-tfXW1-qO.js";
+import { a as tenantClaimPaths, o as tenantFrom, s as tenantPathsFor } from "../claims-PqzCxaTD.js";
+import { n as ttlSeconds, t as TTL } from "../ttl-Hr34gRu8.js";
+import { i as sqlString, n as slug, r as sqlIdent, t as parseTemplate } from "../template--jDkl3UP.js";
+import { t as storageImageUrl } from "../image-url-pIVlO6R1.js";
+import { t as fromStorageError } from "../errors-DLjJHPLK.js";
+import { r as accessCheck } from "../access-sql-B0dF-SoF.js";
+//#region src/storage/versioning.ts
+const MAX_DAYS = 2147483647;
+function wholeIn(value, min, max) {
+	return Number.isInteger(value) && value >= min && value <= max;
+}
+/** Checks a lifecycle policy and fills Storage's defaults; throws a `TypeError` for one Storage would refuse. */
+function lifecyclePayload(id, lifecycle) {
+	const rules = lifecycle.rules;
+	if (rules.length === 0 || rules.length > 1e3) throw new TypeError(`defineBucket("${id}"): lifecycle needs 1 to 1000 rules`);
+	const ids = rules.flatMap((rule) => rule.id === void 0 ? [] : [rule.id]);
+	if (new Set(ids).size !== ids.length) throw new TypeError(`defineBucket("${id}"): lifecycle rule ids repeat`);
+	return { rules: rules.map((rule) => {
+		const { noncurrentDays, newerNoncurrentVersions } = rule.noncurrentVersionExpiration;
+		if (!wholeIn(noncurrentDays, 1, MAX_DAYS)) throw new TypeError(`defineBucket("${id}"): noncurrentDays must be a whole number of days, at least 1`);
+		if (newerNoncurrentVersions !== void 0 && !wholeIn(newerNoncurrentVersions, 1, 100)) throw new TypeError(`defineBucket("${id}"): newerNoncurrentVersions must be 1 to 100`);
+		return {
+			...rule.id === void 0 ? {} : { id: rule.id },
+			status: rule.status ?? "Enabled",
+			filter: {},
+			noncurrentVersionExpiration: {
+				noncurrentDays,
+				...newerNoncurrentVersions === void 0 ? {} : { newerNoncurrentVersions }
+			}
+		};
+	}) };
+}
+function ruleKey(rule) {
+	if (typeof rule !== "object" || rule === null) return JSON.stringify(rule);
+	const entry = rule;
+	const expiration = entry.noncurrentVersionExpiration ?? {};
+	return JSON.stringify([
+		entry.status ?? "Enabled",
+		expiration.noncurrentDays,
+		expiration.newerNoncurrentVersions ?? null
+	]);
+}
+/**
+* Whether a stored `lifecycle_configuration` matches the expected payload.
+* Generated rule ids are ignored; the rules compare as a set.
+*/
+function sameLifecycle(expected, actual) {
+	const stored = typeof actual === "object" && actual !== null && "rules" in actual && Array.isArray(actual.rules) ? actual.rules : [];
+	const want = (expected?.rules ?? []).map(ruleKey).sort();
+	const have = stored.map(ruleKey).sort();
+	return want.length === have.length && want.every((key, i) => key === have[i]);
+}
+/** Storage codes for a lifecycle that is absent or a feature the project doesn't have. */
+function lifecycleAbsent(error) {
+	return error.code === "NoSuchLifecycleConfiguration" || error.kind === "unsupported";
+}
+function toVersion(item) {
+	if (!item.version) return void 0;
+	const metadata = item.metadata ?? {};
+	const size = metadata["size"];
+	const type = metadata["mimetype"];
+	return {
+		versionId: item.version,
+		current: !item.archived_at,
+		deleteMarker: item.is_delete_marker === true,
+		...typeof size === "number" ? { size } : {},
+		...typeof type === "string" ? { contentType: type } : {},
+		createdAt: item.created_at ?? null,
+		archivedAt: item.archived_at ?? null
+	};
+}
+//#endregion
+//#region src/storage/apply.ts
+/**
+* Creates or updates a bucket through the Storage API, then sets or removes
+* its lifecycle policy. Versioning and lifecycle live behind the API, so
+* `bucket.sql()` can't write them.
+*/
+function applyBucket(settings, client) {
+	const storage = client.storage;
+	const fail = (raw) => err(fromStorageError(raw, settings.id));
+	return AsyncResult.from(async () => {
+		try {
+			const limits = {
+				public: settings.public,
+				fileSizeLimit: settings.fileSizeLimit ?? null,
+				allowedMimeTypes: settings.allowedMimeTypes ? [...settings.allowedMimeTypes] : null
+			};
+			const found = await storage.getBucket(settings.id);
+			const missing = found.error !== null && fromStorageError(found.error).kind === "not_found";
+			if (found.error && !missing) return fail(found.error);
+			if (missing) {
+				const created = await storage.createBucket(settings.id, {
+					...limits,
+					...settings.versioning ? { versioningStatus: "ENABLED" } : {}
+				});
+				if (created.error) return fail(created.error);
+			} else {
+				const current = found.data?.versioning_status;
+				const versioningStatus = settings.versioning ? "ENABLED" : current === "ENABLED" ? "SUSPENDED" : void 0;
+				const updated = await storage.updateBucket(settings.id, {
+					...limits,
+					...versioningStatus ? { versioningStatus } : {}
+				});
+				if (updated.error) return fail(updated.error);
+			}
+			if (settings.lifecycle) {
+				const set = await storage.updateBucketLifecycle(settings.id, { rules: settings.lifecycle.rules.map((rule) => ({ ...rule })) });
+				if (set.error) return fail(set.error);
+			} else if (!missing) {
+				const removed = await storage.deleteBucketLifecycle(settings.id);
+				if (removed.error && !lifecycleAbsent(fromStorageError(removed.error))) return fail(removed.error);
+			}
+			return ok({ created: missing });
+		} catch (cause) {
+			return fail(cause);
+		}
+	});
+}
+//#endregion
+//#region src/storage/layouts.ts
+const SAFE_SEGMENT = /^[\w!\-.*'() &$@=;:+,?]+$/;
+function validateSegment(_name, value) {
+	if (value === "." || value === "..") return "is a relative path";
+	if (!SAFE_SEGMENT.test(value)) return "contains characters Storage does not allow";
+}
+const keysOf = (values) => Object.keys(values).filter((key) => values[key] !== void 0);
+/** The longest folder, segment by segment, that holds every one of `folders`. */
+function commonFolder(folders) {
+	const split = folders.map((folder) => folder ? folder.split("/") : []);
+	const shared = [];
+	for (const [index, segment] of (split[0] ?? []).entries()) {
+		if (split.some((parts) => parts[index] !== segment)) break;
+		shared.push(segment);
+	}
+	return shared.join("/");
+}
+function pathLayouts(id, path, sqlString) {
+	const sources = typeof path === "string" ? [path] : path;
+	if (sources.length === 0) throw new TypeError(`defineBucket(${id}): path needs a template`);
+	const layouts = sources.map((source) => parseTemplate(source, "/", validateSegment, { rest: true }));
+	const layoutFor = (values) => {
+		if (layouts.length === 1) return layouts[0];
+		const keys = keysOf(values);
+		const layout = layouts.find((candidate) => candidate.params.length === keys.length && candidate.params.every((name) => keys.includes(name)));
+		if (layout) return layout;
+		throw new DbException(dbError("invalid_input", `No path template of bucket "${id}" takes exactly {${keys.join(", ")}}`));
+	};
+	const patterns = layouts.map((layout) => `name ~ ${sqlString(layout.sqlPattern)}`);
+	return {
+		sources,
+		params: [...new Set(layouts.flatMap((layout) => layout.params))],
+		build(values) {
+			const filled = values;
+			return layoutFor(values).build(filled);
+		},
+		match(value) {
+			for (const layout of layouts) {
+				const values = layout.match(value);
+				if (values) return values;
+			}
+			return null;
+		},
+		prefix(values) {
+			const given = keysOf(values);
+			const fitting = layouts.filter((layout) => given.every((key) => layout.params.includes(key)));
+			return commonFolder((fitting.length > 0 ? fitting : layouts).map((layout) => layout.prefix(values, layout.rest === void 0 ? layout.segments - 1 : layout.segments)));
+		},
+		segmentOf(param, kind) {
+			const indexes = layouts.map((layout) => {
+				const index = layout.segmentOf(param);
+				if (index === void 0) throw new TypeError(`defineBucket: a ${kind} policy needs {${param}} as a whole path segment in "${layout.source}"`);
+				return index;
+			});
+			if (new Set(indexes).size > 1) throw new TypeError(`defineBucket: a ${kind} policy needs {${param}} at the same segment in every path of "${id}"`);
+			return indexes[0];
+		},
+		requireParam(param, label) {
+			for (const layout of layouts) if (!layout.params.includes(param)) throw new TypeError(`defineBucket: ${label} {${param}} is not in "${layout.source}"`);
+		},
+		sqlMatch: patterns.length === 1 ? patterns[0] : `(${patterns.join(" or ")})`
+	};
+}
+/** Whether matched path values hold every value of `within`; a rest value may sit under it. */
+function inScope(values, within) {
+	if (!values) return false;
+	return Object.entries(within).every(([key, expected]) => {
+		if (expected === void 0) return true;
+		const actual = String(values[key]);
+		return actual === String(expected) || actual.startsWith(`${String(expected)}/`);
+	});
+}
+//#endregion
+//#region src/storage/progress.ts
+/** The runtime's `XMLHttpRequest`, or `undefined` (Node, workers). */
+function xhrConstructor() {
+	const runtime = globalThis;
+	return typeof runtime.XMLHttpRequest === "function" ? runtime.XMLHttpRequest : void 0;
+}
+/** Bodies `XMLHttpRequest.send` takes; streams go through storage-js instead. */
+function sendable(body) {
+	return !(typeof ReadableStream !== "undefined" && body instanceof ReadableStream);
+}
+/**
+* PUTs `body` to a signed upload URL with upload progress events. Resolves
+* with `undefined` on success or the failure to map.
+*/
+function xhrUpload(Request, url, body, options) {
+	return new Promise((resolve) => {
+		const xhr = new Request();
+		const onAbort = () => {
+			xhr.abort();
+		};
+		const done = (failure) => {
+			options.signal?.removeEventListener("abort", onAbort);
+			resolve(failure);
+		};
+		xhr.open("PUT", url);
+		xhr.setRequestHeader("x-upsert", String(options.upsert));
+		xhr.setRequestHeader("cache-control", `max-age=${options.cacheControl ?? "3600"}`);
+		const type = options.contentType ?? (typeof Blob !== "undefined" && body instanceof Blob && body.type ? body.type : void 0);
+		if (type) xhr.setRequestHeader("content-type", type);
+		xhr.upload.onprogress = (event) => {
+			if (event.lengthComputable && event.total > 0) options.onProgress(Math.min(1, event.loaded / event.total));
+		};
+		xhr.onload = () => {
+			if (xhr.status >= 200 && xhr.status < 300) {
+				options.onProgress(1);
+				done(void 0);
+				return;
+			}
+			done(parseFailure(xhr.status, xhr.responseText));
+		};
+		xhr.onerror = () => {
+			done({
+				message: "Upload failed",
+				statusCode: "0",
+				name: "StorageUnknownError"
+			});
+		};
+		xhr.onabort = () => {
+			done({
+				message: "The upload was aborted",
+				statusCode: "0",
+				name: "AbortError"
+			});
+		};
+		options.signal?.addEventListener("abort", onAbort, { once: true });
+		xhr.send(body);
+	});
+}
+function parseFailure(status, text) {
+	let message = `Upload failed with status ${String(status)}`;
+	let statusCode = String(status);
+	try {
+		const parsed = JSON.parse(text);
+		if (typeof parsed === "object" && parsed !== null) {
+			const fields = parsed;
+			if (typeof fields.message === "string") message = fields.message;
+			if (typeof fields.statusCode === "string") statusCode = fields.statusCode;
+		}
+	} catch {}
+	return {
+		message,
+		statusCode
+	};
+}
+//#endregion
+//#region src/storage/connect.ts
+/** Folder listings in flight at once while `list` walks a tree. */
+const LIST_CONCURRENCY = 4;
+/** Signed URLs kept per connected bucket; the oldest goes first. */
+const SIGNED_CACHE_SIZE = 500;
+/** Runs at most `limit` of the calls passed to the returned function at once. */
+function pool(limit) {
+	let active = 0;
+	const waiting = [];
+	return async (fn) => {
+		if (active < limit) active++;
+		else await new Promise((resolve) => {
+			waiting.push(resolve);
+		});
+		try {
+			return await fn();
+		} finally {
+			const next = waiting.shift();
+			if (next) next();
+			else active--;
+		}
+	};
+}
+function bodyInfo(body, contentType) {
+	const info = {};
+	if (typeof Blob !== "undefined" && body instanceof Blob) {
+		info.size = body.size;
+		if (body.type) info.type = body.type;
+	} else if (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) info.size = body.byteLength;
+	if (contentType) info.type = contentType;
+	return info;
+}
+/** Rejects with the signal's reason when it aborts before `promise` settles. */
+async function abortable(promise, signal) {
+	if (!signal) return promise;
+	signal.throwIfAborted();
+	let abort = () => {};
+	const aborted = new Promise((_, reject) => {
+		abort = () => {
+			const reason = signal.reason;
+			reject(reason instanceof Error ? reason : new Error(String(reason)));
+		};
+		signal.addEventListener("abort", abort, { once: true });
+	});
+	try {
+		return await Promise.race([promise, aborted]);
+	} finally {
+		signal.removeEventListener("abort", abort);
+	}
+}
+function isErrorResult(value) {
+	return typeof value === "object" && value !== null && value.ok === false && "error" in value;
+}
+function connectBucket(bucket, client, resolveTarget, connectOptions, guard) {
+	const resolve = (target) => {
+		const path = resolveTarget(target);
+		return guard ? guard.path(path) : path;
+	};
+	const scopedWithin = (within) => guard ? {
+		...within,
+		[guard.param]: guard.within(within)
+	} : within ?? {};
+	const api = () => client.storage.from(bucket.id);
+	const signed = connectOptions.cacheSignedUrls ? /* @__PURE__ */ new Map() : void 0;
+	/** Drops cached signed URLs for `paths`; keys start with the JSON-quoted path. */
+	const evict = (paths) => {
+		if (!signed || signed.size === 0) return;
+		const prefixes = paths.map((path) => `[${JSON.stringify(path)},`);
+		for (const key of signed.keys()) if (prefixes.some((prefix) => key.startsWith(prefix))) signed.delete(key);
+	};
+	const run = (fn) => AsyncResult.from(async () => {
+		try {
+			const { data, error } = await fn();
+			return error || data === null ? err(fromStorageError(error, bucket.id)) : ok(data);
+		} catch (cause) {
+			return err(fromStorageError(cause, bucket.id));
+		}
+	});
+	const fileOptions = (options, contentType) => ({
+		...contentType ? { contentType } : {},
+		...options?.cacheControl ? { cacheControl: options.cacheControl } : {},
+		...options?.metadata ? { metadata: { ...options.metadata } } : {},
+		upsert: options?.upsert ?? false
+	});
+	const download = (value) => value === void 0 ? {} : { download: value };
+	const urlExtras = (options) => ({
+		...download(options?.download),
+		...options?.transform ? { transform: { ...options.transform } } : {},
+		...options?.cacheNonce ? { cacheNonce: options.cacheNonce } : {},
+		...options?.versionId ? { versionId: options.versionId } : {}
+	});
+	const upload = (target, body, options) => AsyncResult.from(async () => {
+		options?.signal?.throwIfAborted();
+		const path = resolve(target);
+		const contentType = options?.contentType;
+		const problem = bucket.check(bodyInfo(body, contentType));
+		if (problem) return err(problem);
+		const Request = options?.onProgress ? xhrConstructor() : void 0;
+		if (options?.onProgress && Request && !options.metadata && sendable(body)) {
+			const reserved = await run(() => api().createSignedUploadUrl(path, options.upsert ? { upsert: true } : void 0));
+			if (!reserved.ok) return reserved;
+			const failure = await xhrUpload(Request, reserved.data.signedUrl, body, {
+				contentType,
+				cacheControl: options.cacheControl,
+				upsert: options.upsert ?? false,
+				signal: options.signal,
+				onProgress: options.onProgress
+			});
+			if (failure) return err(fromStorageError(failure, bucket.id));
+			evict([path]);
+			return ok({ path });
+		}
+		return run(() => abortable(api().upload(path, body, fileOptions(options, contentType)), options?.signal)).map(() => {
+			evict([path]);
+			options?.onProgress?.(1);
+			return { path };
+		});
+	});
+	const remove = (targets) => AsyncResult.from(async () => {
+		const paths = targets.map(resolve);
+		if (paths.length === 0) return ok([]);
+		return run(() => api().remove(paths)).map(() => {
+			evict(paths);
+			return paths;
+		});
+	});
+	const transfer = (method) => (from, to, options) => AsyncResult.from(async () => {
+		const [source, path] = [resolve(from), resolve(to)];
+		return run(() => api()[method](source, path, options?.versionId ? { sourceVersionId: options.versionId } : void 0)).map(() => {
+			evict(method === "move" ? [source, path] : [path]);
+			return { path };
+		});
+	});
+	const versions = (target, options) => AsyncResult.from(async () => {
+		const path = resolve(target);
+		const out = [];
+		for (let cursor;;) {
+			options?.signal?.throwIfAborted();
+			const { data, error } = await api().listV2({
+				prefix: path,
+				exactMatch: true,
+				noncurrentVersions: "include",
+				deleteMarkers: "include",
+				sortBy: {
+					column: "created_at",
+					order: "desc"
+				},
+				...cursor ? { cursor } : {}
+			}, options?.signal ? { signal: options.signal } : {});
+			if (error) return err(fromStorageError(error, bucket.id));
+			for (const item of data.objects) {
+				const version = toVersion(item);
+				if (version) out.push(version);
+			}
+			if (!data.hasNext || !data.nextCursor) return ok(out);
+			cursor = data.nextCursor;
+		}
+	});
+	const toObject = (path, item) => {
+		const metadata = item.metadata ?? {};
+		return {
+			path,
+			...typeof metadata.size === "number" ? { size: metadata.size } : {},
+			...metadata.mimetype ? { contentType: metadata.mimetype } : {},
+			createdAt: item.created_at,
+			updatedAt: item.updated_at
+		};
+	};
+	const PAGE = 1e3;
+	const page = async (folder, offset, signal) => {
+		signal?.throwIfAborted();
+		const { data, error } = await api().list(folder, {
+			limit: PAGE,
+			offset,
+			sortBy: {
+				column: "name",
+				order: "asc"
+			}
+		}, signal ? { signal } : {});
+		if (error) throw new DbException(fromStorageError(error, bucket.id));
+		return data;
+	};
+	const walk = async (folder, signal, request) => {
+		const parts = [];
+		for (let offset = 0;; offset += PAGE) {
+			const data = await request(() => page(folder, offset, signal));
+			for (const item of data) {
+				const path = folder ? `${folder}/${item.name}` : item.name;
+				if (item.id === null) {
+					const nested = walk(path, signal, request);
+					nested.catch(() => void 0);
+					parts.push(nested);
+				} else parts.push(toObject(path, item));
+			}
+			if (data.length < PAGE) break;
+		}
+		const out = [];
+		for (const part of parts) if (part instanceof Promise) for (const each of await part) out.push(each);
+		else out.push(part);
+		return out;
+	};
+	/** Yields objects one listing page at a time, depth first, in `list` order. */
+	async function* stream(folder, signal) {
+		for (let offset = 0;; offset += PAGE) {
+			const data = await page(folder, offset, signal);
+			for (const item of data) {
+				const path = folder ? `${folder}/${item.name}` : item.name;
+				if (item.id === null) yield* stream(path, signal);
+				else yield toObject(path, item);
+			}
+			if (data.length < PAGE) return;
+		}
+	}
+	const list = (within, options) => AsyncResult.from(async () => ok(await walk(bucket.prefix(scopedWithin(within)), options?.signal, pool(LIST_CONCURRENCY)))).mapError((error) => ({
+		...error,
+		table: bucket.id
+	}));
+	const signedUrl = (target, options) => AsyncResult.from(async () => {
+		const path = resolve(target);
+		const ttl = ttlSeconds(options?.ttl);
+		const key = signed ? JSON.stringify([
+			path,
+			ttl,
+			options?.transform,
+			options?.download,
+			options?.cacheNonce,
+			options?.versionId
+		]) : "";
+		const cached = signed?.get(key);
+		if (cached) {
+			if (cached.until > Date.now()) return ok(cached.url);
+			signed?.delete(key);
+		}
+		const result = await run(() => api().createSignedUrl(path, ttl, urlExtras(options))).map((data) => data.signedUrl);
+		if (signed && result.ok) {
+			const margin = Math.min(60, ttl / 10);
+			if (signed.size >= SIGNED_CACHE_SIZE) {
+				const oldest = signed.keys().next();
+				if (!oldest.done) signed.delete(oldest.value);
+			}
+			signed.set(key, {
+				url: result.data,
+				until: Date.now() + (ttl - margin) * 1e3
+			});
+		}
+		return result;
+	});
+	return {
+		bucket,
+		path: (target) => {
+			try {
+				return ok(resolve(target));
+			} catch (cause) {
+				return err(toDbError(cause));
+			}
+		},
+		upload,
+		download: (target, options) => AsyncResult.from(async () => {
+			const path = resolve(target);
+			return run(() => api().download(path, options?.versionId ? { versionId: options.versionId } : {}, options?.signal ? { signal: options.signal } : {}));
+		}),
+		exists: (target) => AsyncResult.from(async () => {
+			const path = resolve(target);
+			let found;
+			try {
+				found = await api().exists(path);
+			} catch (cause) {
+				return err(fromStorageError(cause, bucket.id));
+			}
+			if (found.data && !found.error) return ok(true);
+			if (!found.error) return ok(false);
+			const error = fromStorageError(found.error, bucket.id);
+			return error.status === 400 || error.status === 404 ? ok(false) : err(error);
+		}),
+		remove,
+		copy: transfer("copy"),
+		move: transfer("move"),
+		versions,
+		removeVersions: (target, versionIds) => AsyncResult.from(async () => {
+			const path = resolve(target);
+			if (versionIds.length === 0) return ok([]);
+			return run(() => api().remove(versionIds.map((versionId) => ({
+				path,
+				versionId
+			})))).map(() => {
+				evict([path]);
+				return versionIds;
+			});
+		}),
+		purgeCache: (target, options) => AsyncResult.from(async () => {
+			const path = resolve(target);
+			return run(() => api().purgeCache(path, options?.transformations ? { transformations: true } : {}, options?.signal ? { signal: options.signal } : {})).map(() => void 0);
+		}),
+		list,
+		signedUrl,
+		signedUrls: (targets, options) => AsyncResult.from(async () => {
+			const paths = targets.map(resolve);
+			if (paths.length === 0) return ok([]);
+			return run(() => api().createSignedUrls(paths, ttlSeconds(options?.ttl), {
+				...download(options?.download),
+				...options?.cacheNonce ? { cacheNonce: options.cacheNonce } : {}
+			})).andThen((data) => {
+				const failed = data.find((entry) => entry.error != null || !entry.signedUrl);
+				if (failed) return Promise.resolve(err(dbError("not_found", failed.error ?? `No URL for ${String(failed.path)}`, { table: bucket.id })));
+				return Promise.resolve(ok(data.map((entry) => entry.signedUrl)));
+			});
+		}),
+		publicUrl(target, options) {
+			try {
+				return ok(api().getPublicUrl(resolve(target), urlExtras(options)).data.publicUrl);
+			} catch (cause) {
+				return err(toDbError(cause));
+			}
+		},
+		renderUrl(target, transform, options) {
+			if (!bucket.public) return signedUrl(target, {
+				...options,
+				transform
+			});
+			return AsyncResult.from(() => Promise.resolve(ok(api().getPublicUrl(resolve(target), urlExtras({
+				...options,
+				transform
+			})).data.publicUrl)));
+		},
+		replace: (target, body, options = {}) => AsyncResult.from(async () => {
+			const path = resolve(target);
+			const previous = options.previous == null ? null : resolve(options.previous);
+			const same = previous === path;
+			const uploaded = await upload(path, body, {
+				...options,
+				upsert: same || (options.upsert ?? false)
+			});
+			if (!uploaded.ok) return uploaded;
+			const undo = async (error) => {
+				if (!same) await remove([path]);
+				return err(error);
+			};
+			try {
+				options.signal?.throwIfAborted();
+				const outcome = await options.commit?.(path);
+				if (isErrorResult(outcome)) return await undo(outcome.error);
+			} catch (cause) {
+				return undo(fromStorageError(cause, bucket.id));
+			}
+			if (!previous || same) return ok({
+				path,
+				removed: null
+			});
+			const removed = await run(() => api().remove([previous]));
+			if (removed.ok) evict([previous]);
+			return ok(removed.ok ? {
+				path,
+				removed: previous
+			} : {
+				path,
+				removed: null,
+				cleanup: removed.error
+			});
+		}),
+		reserve: (target, options) => AsyncResult.from(async () => {
+			const path = resolve(target);
+			return run(() => api().createSignedUploadUrl(path, options?.upsert ? { upsert: true } : void 0)).map((data) => ({
+				path: data.path,
+				token: data.token,
+				signedUrl: data.signedUrl
+			}));
+		}),
+		uploadReserved: (reservation, body, options) => AsyncResult.from(async () => {
+			options?.signal?.throwIfAborted();
+			const path = resolve(reservation.path);
+			const problem = bucket.check(bodyInfo(body, options?.contentType));
+			if (problem) return err(problem);
+			return run(() => api().uploadToSignedUrl(path, reservation.token, body, fileOptions(options, options?.contentType))).map(() => {
+				evict([path]);
+				return { path };
+			});
+		}),
+		sweep: (options) => AsyncResult.from(async () => {
+			const namespace = optionalTemporal();
+			if (namespace === void 0) return err(temporalMissing());
+			const now = options.now?.() ?? namespace.Now.instant();
+			const cutoff = options.olderThan instanceof namespace.Instant ? options.olderThan.epochMilliseconds : now.epochMilliseconds - options.olderThan.total("milliseconds");
+			const scope = scopedWithin(options.within);
+			const size = options.batchSize ?? 100;
+			const orphans = [];
+			const removed = [];
+			let scanned = 0;
+			let batch = [];
+			const check = async () => {
+				options.signal?.throwIfAborted();
+				const keep = new Set(await options.referenced(batch));
+				for (const path of batch) if (!keep.has(path)) orphans.push(path);
+				batch = [];
+			};
+			try {
+				for await (const object of stream(bucket.prefix(scope), options.signal)) {
+					scanned++;
+					if (!inScope(bucket.match(object.path), scope)) continue;
+					const created = Date.parse(object.createdAt ?? object.updatedAt ?? "");
+					if (!Number.isFinite(created) || created >= cutoff) continue;
+					batch.push(object.path);
+					if (batch.length >= size) await check();
+				}
+				if (batch.length > 0) await check();
+			} catch (cause) {
+				return err({
+					...toDbError(cause),
+					table: bucket.id
+				});
+			}
+			for (let index = 0; index < orphans.length && !options.dryRun;) {
+				options.signal?.throwIfAborted();
+				const chunk = orphans.slice(index, index + size);
+				const result = await run(() => api().remove(chunk));
+				if (!result.ok) return result;
+				evict(chunk);
+				removed.push(...chunk);
+				index += size;
+			}
+			return ok({
+				scanned,
+				orphans,
+				removed
+			});
+		})
+	};
+}
+//#endregion
 //#region src/storage/policy.ts
 /**
-* The checks of a PermDock or access contract policy, or `undefined` for a
-* named policy. `segmentOf` returns the tenant segment, or throws when the
-* path has none.
+* The checks of an access policy, or `undefined` for a named policy.
+* `segmentOf` returns the tenant segment, or throws when the path has none.
 */
 function policyChecks(config, policy, segmentOf) {
 	if (typeof policy === "string") return void 0;
-	let check;
-	let keys;
-	if ("permdock" in policy) {
-		const where = `defineBucket(${config.id})`;
-		const id = policy.scope === "global" ? void 0 : `split_part(name, '/', ${String(policy.segment ?? segmentOf("PermDock"))})`;
-		check = (key) => permdockCheck(where, policy, key, id, config.catalog);
-		keys = policy.permdock;
-	} else {
-		const segment = policy.segment ?? (policy.scope === "platform" ? void 0 : segmentOf("permission"));
-		check = (key) => segment === void 0 ? `(select better_supabase.is_platform(${sqlString(key)}))` : `split_part(name, '/', ${String(segment)}) in (select t::text from better_supabase.tenant_ids_with(${sqlString(key)}) t)`;
-		keys = policy.access;
-	}
+	const where = `defineBucket(${config.id})`;
+	const segment = policy.segment ?? (policy.scope === "platform" ? void 0 : segmentOf("permission"));
+	const id = segment === void 0 || policy.scope === "platform" ? void 0 : `split_part(name, '/', ${String(segment)})`;
+	const check = (key) => accessCheck(where, policy, key, id);
+	const keys = policy.access;
 	return {
 		read: check(keys.read),
 		...keys.list === void 0 ? {} : { list: check(keys.list) },
@@ -37,16 +723,8 @@ function policyChecks(config, policy, segmentOf) {
 //#region src/storage/tenant-scope.ts
 const forbidden = (bucket, message) => new DbException(dbError("forbidden", message, { table: bucket }));
 function resolveTenant(options, claim) {
-	const { context } = options;
 	if (options.tenant !== void 0) return options.tenant;
-	if (!context) return void 0;
-	const tenant = tenantOf(context);
-	if (tenant !== void 0) return tenant;
-	const paths = typeof claim === "string" ? [claim] : claim ?? tenantClaimPaths();
-	for (const path of paths) {
-		const value = claimAt(context.claims, path);
-		if (value !== void 0) return value;
-	}
+	return options.context && tenantFrom(options.context, tenantPathsFor(claim));
 }
 /**
 * The guard for a client of bucket `bucket` whose template holds the tenant
@@ -84,12 +762,6 @@ const LIST_OPERATIONS = [
 	"object.list_v2",
 	"s3.object.list"
 ];
-const TTL = {
-	minute: 60,
-	hour: 3600,
-	day: 86400,
-	week: 604800
-};
 const SIZE_UNITS = {
 	b: 1,
 	kb: 1e3,
@@ -103,13 +775,8 @@ function parseSize(value) {
 	if (typeof value === "number") return value;
 	const match = /^\s*(\d+(?:\.\d+)?)\s*([a-z]*)\s*$/i.exec(value);
 	const unit = SIZE_UNITS[(match?.[2] || "b").toLowerCase()];
-	if (!match || unit === void 0) throw new TypeError(`Invalid size "${value}"`);
-	return Math.round(Number(match[1]) * unit);
-}
-const SAFE_SEGMENT = /^[\w!\-.*'() &$@=;:+,?]+$/;
-function validateSegment(_name, value) {
-	if (value === "." || value === "..") return "is a relative path";
-	if (!SAFE_SEGMENT.test(value)) return "contains characters Storage does not allow";
+	if (!match || unit === void 0) throw new TypeError(`Invalid size "${value}"`);
+	return Math.round(Number(match[1]) * unit);
 }
 function claimSql(claim) {
 	const expressions = (typeof claim === "string" ? [claim] : claim).map((path) => {
@@ -119,6 +786,16 @@ function claimSql(claim) {
 	});
 	return expressions.length === 1 ? expressions[0] : `coalesce(${expressions.join(", ")})`;
 }
+/**
+* Path segment `index` equals `value`. A first segment also bounds `name` to
+* the `value/` prefix in the "C" collation, the storage name indexes', so
+* Postgres range-scans one tenant's objects instead of the whole bucket;
+* `like` can't, because its pattern only exists at run time.
+*/
+function segmentCheck(index, value) {
+	const equal = `split_part(name, '/', ${String(index)}) = ${value}`;
+	return index === 1 ? `name collate "C" >= (${value} || '/') and name collate "C" < (${value} || '0') and ${equal}` : equal;
+}
 function mimeAllowed(allowed, type) {
 	const base = type.split(";")[0].trim().toLowerCase();
 	return allowed.some((entry) => {
@@ -134,43 +811,6 @@ function sizeLabel(bytes) {
 	]) if (bytes >= size && bytes % size === 0) return `${String(bytes / size)}${unit}`;
 	return `${String(bytes)}B`;
 }
-/** Maps a Storage error (`StorageApiError`, fetch failures) to a `DbError`. */
-function fromStorageError(raw, table) {
-	if (isDbError(raw)) return raw;
-	if (raw instanceof DbException) return raw.error;
-	if (typeof raw !== "object" || raw === null) return toDbError(raw);
-	const failure = raw;
-	if (failure.name === "AbortError") return toDbError(raw);
-	const message = failure.message ?? "Storage request failed";
-	const code = failure.code ?? failure.statusCode;
-	const base = {
-		...code ? { code } : {},
-		...table ? { table } : {}
-	};
-	const statusCode = Number(failure.statusCode);
-	const status = Number.isFinite(statusCode) && statusCode >= 400 ? statusCode : failure.status ?? 0;
-	if (/row-level security|unauthorized to|AccessDenied/i.test(`${message} ${code ?? ""}`)) return dbError("forbidden", message, base);
-	if (/already exists|duplicate/i.test(`${message} ${code ?? ""}`)) return dbError("conflict", message, base);
-	if (failure.name === "StorageUnknownError" && status === 0) return dbError("network", message, base);
-	switch (status) {
-		case 400: return dbError("invalid_request", message, base);
-		case 401: return dbError("unauthorized", message, base);
-		case 403: return dbError("forbidden", message, base);
-		case 404: return dbError("not_found", message, base);
-		case 409: return dbError("conflict", message, base);
-		case 413:
-		case 415: return dbError("invalid_input", message, {
-			...base,
-			status
-		});
-		case 408:
-		case 429: return dbError("network", message, {
-			...base,
-			status
-		});
-		default: return status >= 500 ? dbError("network", message, base) : dbError("unexpected", message, base);
-	}
-}
 /**
 * A typed Storage bucket: path builders from a template, limits, generated
 * SQL policies and `config.toml`, and helpers for the multi-step work apps
@@ -179,7 +819,7 @@ function fromStorageError(raw, table) {
 * ```ts
 * export const logos = defineBucket({
 *   id: 'customer-logos',
-*   path: '{orgId}/{customerId}/logo/{version}.webp',
+*   path: '{organizationId}/{customerId}/logo/{version}.webp',
 *   policy: 'tenant',
 *   fileSizeLimit: '5MiB',
 *   allowedMimeTypes: ['image/webp'],
@@ -187,41 +827,32 @@ function fromStorageError(raw, table) {
 * ```
 */
 function defineBucket(config) {
-	const template = parseTemplate(config.path, "/", validateSegment);
+	const layouts = pathLayouts(config.id, config.path, sqlString);
 	const policy = config.policy ?? "none";
 	const fileSizeLimit = config.fileSizeLimit === void 0 ? void 0 : parseSize(config.fileSizeLimit);
 	const allowedMimeTypes = config.allowedMimeTypes;
-	function segmentFor(param, kind) {
-		const index = template.segmentOf(param);
-		if (index === void 0) throw new TypeError(`defineBucket: a ${kind} policy needs {${param}} as a whole path segment in "${config.path}"`);
-		return index;
-	}
-	const tenantParam = config.tenant ? config.tenant.param ?? "orgId" : void 0;
-	if (tenantParam !== void 0 && !template.params.includes(tenantParam)) throw new TypeError(`defineBucket: tenant.param {${tenantParam}} is not in "${config.path}"`);
+	const versioning = config.versioning ?? false;
+	if (config.lifecycle && !versioning) throw new TypeError(`defineBucket("${config.id}"): lifecycle expires noncurrent versions, so it needs versioning: true`);
+	const lifecycle = config.lifecycle ? lifecyclePayload(config.id, config.lifecycle) : void 0;
+	const segmentFor = (param, kind) => layouts.segmentOf(param, kind);
+	const tenantParam = config.tenant ? config.tenant.param ?? "organizationId" : void 0;
+	if (tenantParam !== void 0) layouts.requireParam(tenantParam, "tenant.param");
 	const tenantClaim = config.tenant?.claim;
-	const mode = typeof policy === "string" ? policy : "permdock" in policy ? "permdock" : "access";
+	const mode = typeof policy === "string" ? policy : "access";
 	const accessCheck = (() => {
 		switch (mode) {
-			case "tenant": {
-				const index = segmentFor(config.tenant?.param ?? "orgId", "tenant");
-				const expression = config.tenant?.sql ?? claimSql(config.tenant?.claim ?? tenantClaimPaths());
-				return `split_part(name, '/', ${String(index)}) = (${expression})`;
-			}
-			case "owner": {
-				const index = segmentFor(config.owner?.param ?? "userId", "owner");
-				return `split_part(name, '/', ${String(index)}) = (select auth.uid())::text`;
-			}
+			case "tenant": return segmentCheck(segmentFor(config.tenant?.param ?? "organizationId", "tenant"), `(${config.tenant?.sql ?? claimSql(config.tenant?.claim ?? tenantClaimPaths())})`);
+			case "owner": return segmentCheck(segmentFor(config.owner?.param ?? "userId", "owner"), "(select auth.uid())::text");
 			case "public":
 			case "none":
-			case "permdock":
 			case "access": return;
 			default: throw new TypeError(`defineBucket: unknown policy "${String(mode)}"`);
 		}
 	})();
-	const permdock = policyChecks(config, policy, (kind) => segmentFor(config.tenant?.param ?? "orgId", kind));
+	const permission = policyChecks(config, policy, (kind) => segmentFor(config.tenant?.param ?? "organizationId", kind));
 	const resolve = (target) => {
-		if (typeof target !== "string") return template.build(target);
-		if (!template.match(target)) throw new DbException(dbError("invalid_input", `Path "${target}" does not match "${config.path}"`));
+		if (typeof target !== "string") return layouts.build(target);
+		if (!layouts.match(target)) throw new DbException(dbError("invalid_input", `Path "${target}" does not match "${layouts.sources.join("\" or \"")}"`));
 		return target;
 	};
 	const check = (file) => {
@@ -230,23 +861,32 @@ function defineBucket(config) {
 	};
 	const bucket = {
 		id: config.id,
-		template: config.path,
-		params: template.params,
-		owner: policy === "owner" ? config.owner?.param ?? "userId" : template.params.includes("userId") ? "userId" : void 0,
+		template: layouts.sources[0],
+		templates: layouts.sources,
+		params: layouts.params,
+		owner: policy === "owner" ? config.owner?.param ?? "userId" : layouts.params.includes("userId") ? "userId" : void 0,
 		tenant: tenantParam,
 		public: config.public ?? false,
 		policy,
 		fileSizeLimit,
 		allowedMimeTypes,
-		path: (values) => template.build(values),
-		match: (path) => template.match(path),
-		prefix: (values = {}) => template.prefix(values, template.segments - 1),
+		versioning,
+		lifecycle: config.lifecycle,
+		path: (values) => {
+			try {
+				return ok(layouts.build(values));
+			} catch (cause) {
+				return err(toDbError(cause));
+			}
+		},
+		match: (path) => layouts.match(path),
+		prefix: (values = {}) => layouts.prefix(values),
 		check,
 		sql() {
 			const id = sqlString(config.id);
 			const name = slug(config.id);
 			const lines = [
-				`-- better-supabase: bucket ${config.id} (${config.path})`,
+				`-- better-supabase: bucket ${config.id} (${layouts.sources.join(", ")})`,
 				"insert into storage.buckets (id, name, public, file_size_limit, allowed_mime_types)",
 				`values (${id}, ${id}, ${String(bucket.public)}, ${fileSizeLimit === void 0 ? "null" : String(fileSizeLimit)}, ${allowedMimeTypes ? `array[${allowedMimeTypes.map(sqlString).join(", ")}]` : "null"})`,
 				"on conflict (id) do update set public = excluded.public, file_size_limit = excluded.file_size_limit,",
@@ -254,7 +894,7 @@ function defineBucket(config) {
 			];
 			const policies = [];
 			const inBucket = `bucket_id = ${id}`;
-			const pathMatch = `name ~ ${sqlString(template.sqlPattern)}`;
+			const pathMatch = layouts.sqlMatch;
 			if (accessCheck) {
 				const using = `${inBucket} and ${accessCheck}`;
 				const write = `${using} and ${pathMatch}`;
@@ -291,29 +931,29 @@ function defineBucket(config) {
 				inBucket,
 				void 0
 			]);
-			else if (permdock) {
+			else if (permission) {
 				const listing = `storage.allow_any_operation(array[${LIST_OPERATIONS.map(sqlString).join(", ")}])`;
-				if (permdock.list) policies.push([
+				if (permission.list) policies.push([
 					"select",
 					"select",
 					"authenticated",
-					`${inBucket} and not ${listing} and ${permdock.read}`,
+					`${inBucket} and not ${listing} and ${permission.read}`,
 					void 0
 				], [
 					"list",
 					"select",
 					"authenticated",
-					`${inBucket} and ${listing} and ${permdock.list}`,
+					`${inBucket} and ${listing} and ${permission.list}`,
 					void 0
 				]);
 				else policies.push([
 					"select",
 					"select",
 					"authenticated",
-					`${inBucket} and ${permdock.read}`,
+					`${inBucket} and ${permission.read}`,
 					void 0
 				]);
-				const write = `${inBucket} and ${permdock.write}`;
+				const write = `${inBucket} and ${permission.write}`;
 				policies.push([
 					"insert",
 					"insert",
@@ -330,7 +970,7 @@ function defineBucket(config) {
 					"delete",
 					"delete",
 					"authenticated",
-					`${inBucket} and ${permdock.delete}`,
+					`${inBucket} and ${permission.delete}`,
 					void 0
 				]);
 			}
@@ -338,7 +978,7 @@ function defineBucket(config) {
 				const policyName = sqlIdent(`bs_${name}_${suffix}`);
 				lines.push("", `drop policy if exists ${policyName} on storage.objects;`, `create policy ${policyName} on storage.objects for ${command} to ${roles}${using ? `\n  using (${using})` : ""}${withCheck ? `\n  with check (${withCheck})` : ""};`);
 			}
-			if (permdock && !permdock.list) lines.push("", `drop policy if exists ${sqlIdent(`bs_${name}_list`)} on storage.objects;`);
+			if (permission && !permission.list) lines.push("", `drop policy if exists ${sqlIdent(`bs_${name}_list`)} on storage.objects;`);
 			return `${lines.join("\n")}\n`;
 		},
 		toml() {
@@ -374,257 +1014,88 @@ function defineBucket(config) {
 				actual: actual.allowedMimeTypes,
 				message: `Bucket "${config.id}" allowed MIME types differ`
 			});
+			if (actual.versioning !== void 0 && actual.versioning !== null && actual.versioning === "ENABLED" !== versioning) issues.push({
+				field: "versioning",
+				expected: versioning ? "ENABLED" : "DISABLED or SUSPENDED",
+				actual: actual.versioning,
+				message: `Bucket "${config.id}" versioning is ${actual.versioning}`
+			});
+			if (actual.lifecycle !== void 0 && !sameLifecycle(lifecycle, actual.lifecycle)) issues.push({
+				field: "lifecycle",
+				expected: lifecycle ?? null,
+				actual: actual.lifecycle,
+				message: `Bucket "${config.id}" lifecycle policy differs`
+			});
 			return issues;
 		},
+		apply: (client) => applyBucket({
+			id: config.id,
+			public: bucket.public,
+			fileSizeLimit,
+			allowedMimeTypes,
+			versioning,
+			lifecycle
+		}, client),
 		connect: (client, options = {}) => connectBucket(bucket, client, resolve, options, tenantGuard(bucket.id, tenantParam, tenantClaim, (path) => bucket.match(path), options))
 	};
 	return bucket;
 }
-function bodyInfo(body, contentType) {
-	const info = {};
-	if (typeof Blob !== "undefined" && body instanceof Blob) {
-		info.size = body.size;
-		if (body.type) info.type = body.type;
-	} else if (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) info.size = body.byteLength;
-	if (contentType) info.type = contentType;
-	return info;
-}
-function ttlSeconds(ttl) {
-	return typeof ttl === "number" ? ttl : TTL[ttl ?? "hour"];
-}
-function isErrorResult(value) {
-	return typeof value === "object" && value !== null && value.ok === false && "error" in value;
-}
-function connectBucket(bucket, client, resolveTarget, connectOptions, guard) {
-	const resolve = (target) => {
-		const path = resolveTarget(target);
-		return guard ? guard.path(path) : path;
+//#endregion
+//#region src/storage/registry.ts
+/**
+* A registry of bucket definitions by id, for rows that store a bucket id
+* next to an object path (files, attachments, sources). An id no bucket
+* has, and a path outside the bucket's templates, are errors, never a
+* fallback bucket.
+*
+* ```ts
+* export const buckets = defineBuckets({ files, attachments, logos });
+*
+* const ref = buckets.connectStored(supabase, {
+*   bucket: row.bucketId,
+*   path: row.path,
+* }, { context: db.$context });
+* if (ref.ok) await ref.data.storage.signedUrl(ref.data.path);
+* ```
+*/
+function defineBuckets(buckets) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const [name, bucket] of Object.entries(buckets)) {
+		if (byId.get(bucket.id) !== void 0) throw new TypeError(`defineBuckets: "${name}" reuses the bucket id "${bucket.id}"`);
+		byId.set(bucket.id, bucket);
+	}
+	const lookup = (id) => {
+		const bucket = byId.get(id);
+		return bucket === void 0 ? err(dbError("invalid_input", `Bucket "${id}" is not registered`)) : ok(bucket);
 	};
-	const scopedWithin = (within) => guard ? {
-		...within,
-		[guard.param]: guard.within(within)
-	} : within ?? {};
-	const api = () => client.storage.from(bucket.id);
-	const signed = connectOptions.cacheSignedUrls ? /* @__PURE__ */ new Map() : void 0;
-	const run = (fn) => AsyncResult.from(async () => {
-		try {
-			const { data, error } = await fn();
-			return error || data === null ? err(fromStorageError(error, bucket.id)) : ok(data);
-		} catch (cause) {
-			return err(fromStorageError(cause, bucket.id));
-		}
-	});
-	const fileOptions = (options, contentType) => ({
-		...contentType ? { contentType } : {},
-		...options?.cacheControl ? { cacheControl: options.cacheControl } : {},
-		...options?.metadata ? { metadata: { ...options.metadata } } : {},
-		upsert: options?.upsert ?? false
-	});
-	const download = (value) => value === void 0 ? {} : { download: value };
-	const upload = (target, body, options) => AsyncResult.from(async () => {
-		options?.signal?.throwIfAborted();
-		const path = resolve(target);
-		const contentType = options?.contentType;
-		const problem = bucket.check(bodyInfo(body, contentType));
-		if (problem) return err(problem);
-		return run(() => api().upload(path, body, fileOptions(options, contentType))).map(() => ({ path }));
-	});
-	const remove = (targets) => AsyncResult.from(async () => {
-		const paths = targets.map(resolve);
-		if (paths.length === 0) return ok([]);
-		return run(() => api().remove(paths)).map(() => paths);
-	});
-	const walk = async (folder, signal, out) => {
-		const limit = 1e3;
-		for (let offset = 0;; offset += limit) {
-			signal?.throwIfAborted();
-			const { data, error } = await api().list(folder, {
-				limit,
-				offset,
-				sortBy: {
-					column: "name",
-					order: "asc"
-				}
-			}, signal ? { signal } : {});
-			if (error) throw new DbException(fromStorageError(error, bucket.id));
-			for (const item of data) {
-				const path = folder ? `${folder}/${item.name}` : item.name;
-				if (item.id === null) await walk(path, signal, out);
-				else {
-					const metadata = item.metadata ?? {};
-					out.push({
-						path,
-						...typeof metadata.size === "number" ? { size: metadata.size } : {},
-						...metadata.mimetype ? { contentType: metadata.mimetype } : {},
-						createdAt: item.created_at,
-						updatedAt: item.updated_at
-					});
-				}
-			}
-			if (data.length < limit) return;
-		}
+	const resolve = (ref) => {
+		const found = lookup(ref.bucket);
+		if (!found.ok) return found;
+		const bucket = found.data;
+		if (bucket.match(ref.path) === null) return err(dbError("invalid_input", `Path "${ref.path}" does not match "${bucket.templates.join("\" or \"")}"`, { table: bucket.id }));
+		return ok({
+			bucket,
+			path: ref.path
+		});
 	};
-	const list = (within, options) => AsyncResult.from(async () => {
-		const out = [];
-		await walk(bucket.prefix(scopedWithin(within)), options?.signal, out);
-		return ok(out);
-	}).mapError((error) => ({
-		...error,
-		table: bucket.id
-	}));
-	const signedUrl = (target, options) => AsyncResult.from(async () => {
-		const path = resolve(target);
-		const ttl = ttlSeconds(options?.ttl);
-		const key = signed ? JSON.stringify([
-			path,
-			ttl,
-			options?.transform,
-			options?.download
-		]) : "";
-		const cached = signed?.get(key);
-		if (cached && cached.until > Date.now()) return ok(cached.url);
-		const result = await run(() => api().createSignedUrl(path, ttl, {
-			...download(options?.download),
-			...options?.transform ? { transform: { ...options.transform } } : {}
-		})).map((data) => data.signedUrl);
-		if (signed && result.ok) {
-			const margin = Math.min(60, ttl / 10);
-			signed.set(key, {
-				url: result.data,
-				until: Date.now() + (ttl - margin) * 1e3
-			});
-		}
-		return result;
-	});
 	return {
-		bucket,
-		path: (target) => {
-			try {
-				return ok(resolve(target));
-			} catch (cause) {
-				return err(toDbError(cause));
-			}
-		},
-		upload,
-		download: (target, options) => AsyncResult.from(async () => {
-			const path = resolve(target);
-			return run(() => api().download(path, {}, options?.signal ? { signal: options.signal } : {}));
-		}),
-		exists: (target) => AsyncResult.from(async () => {
-			const path = resolve(target);
-			const found = await api().exists(path);
-			if (!found.data) return ok(false);
-			return found.error ? err(fromStorageError(found.error, bucket.id)) : ok(true);
-		}),
-		remove,
-		list,
-		signedUrl,
-		signedUrls: (targets, options) => AsyncResult.from(async () => {
-			const paths = targets.map(resolve);
-			if (paths.length === 0) return ok([]);
-			return run(() => api().createSignedUrls(paths, ttlSeconds(options?.ttl), download(options?.download))).andThen((data) => {
-				const failed = data.find((entry) => entry.error != null || !entry.signedUrl);
-				if (failed) return Promise.resolve(err(dbError("not_found", failed.error ?? `No URL for ${String(failed.path)}`, { table: bucket.id })));
-				return Promise.resolve(ok(data.map((entry) => entry.signedUrl)));
-			});
-		}),
-		publicUrl(target, options) {
-			const path = resolve(target);
-			return api().getPublicUrl(path, {
-				...download(options?.download),
-				...options?.transform ? { transform: { ...options.transform } } : {}
-			}).data.publicUrl;
-		},
-		renderUrl(target, transform, options) {
-			if (!bucket.public) return signedUrl(target, {
-				...options,
-				transform
-			});
-			return AsyncResult.from(() => Promise.resolve(ok(api().getPublicUrl(resolve(target), {
-				...download(options?.download),
-				transform: { ...transform }
-			}).data.publicUrl)));
-		},
-		replace: (target, body, options = {}) => AsyncResult.from(async () => {
-			const path = resolve(target);
-			const previous = options.previous ?? null;
-			const same = previous === path;
-			const uploaded = await upload(path, body, {
-				...options,
-				upsert: same || (options.upsert ?? false)
-			});
-			if (!uploaded.ok) return uploaded;
-			const undo = async (error) => {
-				if (!same) await remove([path]);
-				return err(error);
-			};
-			try {
-				options.signal?.throwIfAborted();
-				const outcome = await options.commit?.(path);
-				if (isErrorResult(outcome)) return await undo(outcome.error);
-			} catch (cause) {
-				return undo(fromStorageError(cause, bucket.id));
-			}
-			if (!previous || same) return ok({
-				path,
-				removed: null
-			});
-			const removed = await run(() => api().remove([previous]));
-			return ok(removed.ok ? {
-				path,
-				removed: previous
-			} : {
-				path,
-				removed: null,
-				cleanup: removed.error
-			});
-		}),
-		reserve: (target, options) => AsyncResult.from(async () => {
-			const path = resolve(target);
-			return run(() => api().createSignedUploadUrl(path, options?.upsert ? { upsert: true } : void 0)).map((data) => ({
-				path: data.path,
-				token: data.token,
-				signedUrl: data.signedUrl
-			}));
-		}),
-		uploadReserved: (reservation, body, options) => AsyncResult.from(async () => {
-			options?.signal?.throwIfAborted();
-			const path = resolve(reservation.path);
-			const problem = bucket.check(bodyInfo(body, options?.contentType));
-			if (problem) return err(problem);
-			return run(() => api().uploadToSignedUrl(path, reservation.token, body, fileOptions(options, options?.contentType))).map(() => ({ path }));
-		}),
-		sweep: (options) => AsyncResult.from(async () => {
-			const namespace = optionalTemporal();
-			if (namespace === void 0) return err(temporalMissing());
-			const now = options.now?.() ?? namespace.Now.instant();
-			const cutoff = options.olderThan instanceof namespace.Instant ? options.olderThan.epochMilliseconds : now.epochMilliseconds - options.olderThan.total("milliseconds");
-			const found = await list(options.within, options.signal ? { signal: options.signal } : void 0);
-			if (!found.ok) return found;
-			const candidates = found.data.filter((object) => bucket.match(object.path) !== null).filter((object) => {
-				const created = Date.parse(object.createdAt ?? object.updatedAt ?? "");
-				return Number.isFinite(created) && created < cutoff;
-			}).map((object) => object.path);
-			const size = options.batchSize ?? 100;
-			const orphans = [];
-			const removed = [];
-			for (let index = 0; index < candidates.length; index += size) {
-				options.signal?.throwIfAborted();
-				const batch = candidates.slice(index, index + size);
-				const keep = new Set(await options.referenced(batch));
-				const unreferenced = batch.filter((path) => !keep.has(path));
-				orphans.push(...unreferenced);
-				if (options.dryRun || unreferenced.length === 0) continue;
-				const result = await run(() => api().remove(unreferenced));
-				if (!result.ok) return result;
-				removed.push(...unreferenced);
-			}
-			return ok({
-				scanned: found.data.length,
-				orphans,
-				removed
-			});
-		})
+		buckets,
+		ids: [...byId.keys()],
+		has: (id) => byId.has(id),
+		byId: lookup,
+		resolve,
+		connectStored(client, ref, options) {
+			const resolved = resolve(ref);
+			if (!resolved.ok) return resolved;
+			const { bucket } = resolved.data;
+			const storage = bucket.connect(client, options);
+			const path = storage.path(ref.path);
+			return path.ok ? ok({
+				bucket,
+				storage,
+				path: path.data
+			}) : path;
+		}
 	};
 }
 //#endregion
@@ -638,7 +1109,7 @@ const IMAGE_TYPES = [
 	"image/avif"
 ];
 const AVATAR_PATH = "{userId}/avatar-{version}.{ext}";
-const LOGO_PATH = "{orgId}/logo-{version}.{ext}";
+const LOGO_PATH = "{organizationId}/logo-{version}.{ext}";
 /**
 * A bucket for profile pictures: `{userId}/avatar-{version}.{ext}`, public,
 * 2 MiB of images, written only by their owner (the `owner` policy).
@@ -654,13 +1125,13 @@ function avatarBucket(options = {}) {
 	});
 }
 /**
-* A bucket for organization logos: `{orgId}/logo-{version}.{ext}`, public,
+* A bucket for organization logos: `{organizationId}/logo-{version}.{ext}`, public,
 * 2 MiB of images, written by members with the update permission through
 * the access contract (`tenant_ids_with`), so it follows the app's roles.
 */
-function orgLogoBucket(options = {}) {
+function organizationLogoBucket(options = {}) {
 	const permission = options.permission ?? "organization.update";
-	const tenant = options.tenant === false ? void 0 : options.tenant ?? { param: "orgId" };
+	const tenant = options.tenant === false ? void 0 : options.tenant ?? { param: "organizationId" };
 	return defineBucket({
 		id: options.id ?? "organization-logos",
 		path: options.path ?? LOGO_PATH,
@@ -675,4 +1146,192 @@ function orgLogoBucket(options = {}) {
 	});
 }
 //#endregion
-export { IMAGE_TYPES, TTL, avatarBucket, defineBucket, fromStorageError, orgLogoBucket, parseSize };
+//#region src/storage/analytics-bucket.ts
+/**
+* A Storage analytics bucket: Apache Iceberg tables that query engines read
+* through the Iceberg REST catalog.
+*
+* ```ts
+* export const events = defineAnalyticsBucket({ id: "events" });
+* await events.connect(admin).apply().orThrow();
+* ```
+*/
+function defineAnalyticsBucket(config) {
+	return {
+		id: config.id,
+		connect: (client) => ({
+			apply: () => AsyncResult.from(async () => {
+				const analytics = client.storage.analytics;
+				try {
+					const listed = await analytics.listBuckets({ search: config.id });
+					if (listed.error) return err(fromStorageError(listed.error, config.id));
+					if (listed.data.some((bucket) => bucket.name === config.id)) return ok({ created: false });
+					const made = await analytics.createBucket(config.id);
+					if (made.error) return err(fromStorageError(made.error, config.id));
+					return ok({ created: true });
+				} catch (cause) {
+					return err(fromStorageError(cause, config.id));
+				}
+			}),
+			catalog: () => client.storage.analytics.from(config.id)
+		})
+	};
+}
+//#endregion
+//#region src/storage/vector-bucket.ts
+const PUT_BATCH = 500;
+const GET_BATCH = 100;
+function chunks(items, size) {
+	const out = [];
+	for (let index = 0; index < items.length; index += size) out.push(items.slice(index, index + size));
+	return out;
+}
+/** Batches in flight at once for one `put`, `get` or `remove`. */
+const CHUNK_CONCURRENCY = 4;
+/** Runs `run` per item over a few lanes; stops starting items after the first error. */
+async function inLanes(items, run) {
+	const out = [];
+	let next = 0;
+	let failed;
+	const lane = async () => {
+		while (!failed && next < items.length) {
+			const index = next++;
+			const result = await run(items[index]);
+			if (!result.ok) {
+				failed ??= result;
+				return;
+			}
+			out[index] = result.data;
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(CHUNK_CONCURRENCY, items.length) }, lane));
+	return failed ?? ok(out);
+}
+const metricOf = (config) => config.distanceMetric ?? "cosine";
+/**
+* A Storage vector bucket with typed indexes. Storage keeps the vectors
+* outside Postgres; use the `vector-search` module for pgvector in a table.
+*
+* ```ts
+* export const embeddings = defineVectorBucket({
+*   id: "embeddings",
+*   indexes: { documents: { dimension: 1536 } },
+* });
+* const docs = embeddings.connect(admin).index("documents");
+* await docs.put([{ key: doc.id, vector, metadata: { organizationId } }]);
+* ```
+*/
+function defineVectorBucket(config) {
+	for (const [name, index] of Object.entries(config.indexes)) if (!Number.isInteger(index.dimension) || index.dimension < 1) throw new TypeError(`defineVectorBucket("${config.id}"): index "${name}" needs a whole, positive dimension`);
+	return {
+		id: config.id,
+		indexes: config.indexes,
+		connect: (client) => connectVectorBucket(config, client)
+	};
+}
+function connectVectorBucket(config, client) {
+	const vectors = () => client.storage.vectors;
+	const scope = () => vectors().from(config.id);
+	const failure = (raw) => fromStorageError(raw, config.id);
+	const attempt = (fn) => AsyncResult.from(async () => {
+		try {
+			return await fn();
+		} catch (cause) {
+			return err(failure(cause));
+		}
+	});
+	return {
+		apply: () => attempt(async () => {
+			const created = [];
+			const found = await vectors().getBucket(config.id);
+			if (found.error) {
+				if (failure(found.error).kind !== "not_found") return err(failure(found.error));
+				const made = await vectors().createBucket(config.id);
+				if (made.error) return err(failure(made.error));
+			}
+			const entries = Object.entries(config.indexes);
+			for (const [name, index] of entries) {
+				const existing = await scope().getIndex(name);
+				if (existing.data) {
+					const actual = existing.data.index;
+					if (actual.dimension !== index.dimension || actual.distanceMetric !== metricOf(index)) return err(dbError("conflict", `Vector index "${name}" has dimension ${String(actual.dimension)} and metric ${actual.distanceMetric}, not ${String(index.dimension)} and ${metricOf(index)}`, { table: config.id }));
+					continue;
+				}
+				if (failure(existing.error).kind !== "not_found") return err(failure(existing.error));
+				const made = await scope().createIndex({
+					indexName: name,
+					dataType: "float32",
+					dimension: index.dimension,
+					distanceMetric: metricOf(index),
+					...index.nonFilterableMetadataKeys ? { metadataConfiguration: { nonFilterableMetadataKeys: [...index.nonFilterableMetadataKeys] } } : {}
+				});
+				if (made.error) return err(failure(made.error));
+				created.push(name);
+			}
+			return ok({ created });
+		}),
+		index(name) {
+			const settings = config.indexes[name];
+			const api = () => scope().index(name);
+			const checkDimension = (vector, key) => vector.length === settings.dimension ? void 0 : dbError("invalid_input", `${key === void 0 ? "The query vector" : `Vector "${key}"`} has ${String(vector.length)} values; index "${name}" takes ${String(settings.dimension)}`, { table: config.id });
+			const hit = (match) => ({
+				key: match.key,
+				...match.distance === void 0 ? {} : { distance: match.distance },
+				...match.metadata === void 0 ? {} : { metadata: match.metadata },
+				...match.data ? { vector: match.data.float32 } : {}
+			});
+			return {
+				name,
+				dimension: settings.dimension,
+				put: (records) => attempt(async () => {
+					for (const record of records) {
+						const problem = checkDimension(record.vector, record.key);
+						if (problem) return err(problem);
+					}
+					const put = await inLanes(chunks(records, PUT_BATCH), async (batch) => {
+						const { error } = await api().putVectors({ vectors: batch.map((record) => ({
+							key: record.key,
+							data: { float32: [...record.vector] },
+							...record.metadata ? { metadata: { ...record.metadata } } : {}
+						})) });
+						return error ? err(failure(error)) : ok(batch.length);
+					});
+					return put.ok ? ok(records.length) : put;
+				}),
+				query: (vector, options = {}) => attempt(async () => {
+					const problem = checkDimension(vector);
+					if (problem) return err(problem);
+					const found = await api().queryVectors({
+						queryVector: { float32: [...vector] },
+						topK: options.topK ?? 10,
+						returnDistance: true,
+						returnMetadata: options.metadata ?? true,
+						...options.filter ? { filter: { ...options.filter } } : {}
+					});
+					if (found.error) return err(failure(found.error));
+					return ok(found.data.vectors.map(hit));
+				}),
+				get: (keys, options = {}) => attempt(async () => {
+					const found = await inLanes(chunks(keys, GET_BATCH), async (batch) => {
+						const { data, error } = await api().getVectors({
+							keys: batch,
+							returnMetadata: true,
+							returnData: options.vector ?? false
+						});
+						return error ? err(failure(error)) : ok(data.vectors.map(hit));
+					});
+					return found.ok ? ok(found.data.flat()) : found;
+				}),
+				remove: (keys) => attempt(async () => {
+					const removed = await inLanes(chunks(keys, PUT_BATCH), async (batch) => {
+						const { error } = await api().deleteVectors({ keys: batch });
+						return error ? err(failure(error)) : ok(batch.length);
+					});
+					return removed.ok ? ok(keys) : removed;
+				})
+			};
+		}
+	};
+}
+//#endregion
+export { IMAGE_TYPES, TTL, avatarBucket, defineAnalyticsBucket, defineBucket, defineBuckets, defineVectorBucket, fromStorageError, organizationLogoBucket, parseSize, storageImageUrl };