@rebasepro/types 0.17.3 → 0.18.1

package/dist/index.es.js

@@ -30,12 +30,18 @@ var RebaseApiError = class extends Error {
 	code;
 	/** Structured error payload from the server, when present. */
 	details;
+	/** See {@link RebaseErrorInit.requestId}. Quote it in a bug report. */
+	requestId;
+	/** See {@link RebaseErrorInit.retryAfterSeconds}. */
+	retryAfterSeconds;
 	constructor(message, init = {}) {
 		super(message);
 		this.name = "RebaseApiError";
 		this.status = init.status;
 		this.code = init.code;
 		this.details = init.details;
+		this.requestId = init.requestId;
+		this.retryAfterSeconds = init.retryAfterSeconds;
 		if (init.cause !== void 0) this.cause = init.cause;
 	}
 };
@@ -49,11 +55,76 @@ var RebaseApiError = class extends Error {
 * @group Errors
 */
 var RebaseClientError = class extends RebaseApiError {
-	constructor(message) {
-		super(message);
+	/**
+	* `init` is the same one {@link RebaseApiError} takes, and it is what makes
+	* `code` reachable at all.
+	*
+	* The constructor used to accept a message and nothing else, so every
+	* client-side failure — an undefined filter value, an unknown accessor,
+	* `listen()` on a client built with `realtime: false`, a function name with
+	* a `/` in it, `refreshSession()` while signed out — arrived with `code ===
+	* undefined`. The documented `switch (e.code)` in this file's own example
+	* fell to `default: throw e` for all of them, and the only client-side error
+	* that *did* carry a code was `OFFLINE`, because that one path minted a
+	* `RebaseApiError` instead.
+	*/
+	constructor(message, init = {}) {
+		super(message, init);
 		this.name = "RebaseClientError";
 	}
 };
+/**
+* Brand for a contract method a particular client cannot serve.
+*
+* `Symbol.for` rather than a fresh symbol: two copies of `@rebasepro/types` in
+* one tree — which happens, see `docs/dependency-duplication-traps.md` — must
+* agree about it, and a module-local symbol would not.
+*/
+var UNSUPPORTED_METHOD = Symbol.for("rebase.unsupportedMethod");
+/**
+* Build the stub a client installs for a contract method it cannot serve.
+*
+* `listen`, `listenById` and `count` are part of `SDKCollectionClient`, not
+* optional extras — a caller should be able to write
+* `client.data.posts.count()` without asking first, and a transport that cannot
+* serve it should answer with a sentence naming the configuration that would,
+* rather than with `undefined is not a function` at the call site. Where the
+* transport genuinely cannot (a client built with `realtime: false`, a driver
+* with no `listenCollection`), it installs one of these instead of omitting the
+* method.
+*
+* @param message What to tell the caller, naming the fix.
+* @group Errors
+*/
+function unsupportedMethod(message) {
+	const stub = () => {
+		throw new RebaseClientError(message, { code: "REALTIME_DISABLED" });
+	};
+	stub[UNSUPPORTED_METHOD] = true;
+	return stub;
+}
+/**
+* Can this method actually do anything?
+*
+* `true` for a stub from {@link unsupportedMethod} **and** for a method that is
+* simply not there — a partial client, a hand-built test double, an
+* implementation written against an older shape of the interface. Both mean the
+* same thing to a caller, so both answer the same way, and an adapter that
+* checks this cannot be caught out by either.
+*
+* Ordinary code does not need it: calling the method and letting it throw is
+* the normal path. Adapters do — the admin panel chooses between subscribing
+* and a one-shot `find()` by asking whether the client can listen, and a UI
+* that subscribes into a throw is worse than one that polls. This is the
+* question `if (accessor.listen)` used to be asking, made explicit now that the
+* method is always there to call.
+*
+* @group Errors
+*/
+function isUnsupported(method) {
+	if (typeof method !== "function") return true;
+	return method[UNSUPPORTED_METHOD] === true;
+}
 //#endregion
 //#region src/types/entities.ts
 /**
@@ -363,6 +434,7 @@ var ADMIN_COLLECTION_KEYS = [
 	"Actions",
 	"additionalFields",
 	"alwaysApplyDefaultValues",
+	"browserCallbacks",
 	"components",
 	"customViews",
 	"defaultEntityAction",
@@ -430,6 +502,7 @@ var ADMIN_PROPERTY_KEYS = [
 	"Filter",
 	"filterOperators",
 	"fixedFilter",
+	"format",
 	"hideFromCollection",
 	"includeEntityLink",
 	"includeId",
@@ -440,6 +513,7 @@ var ADMIN_PROPERTY_KEYS = [
 	"previewAsTag",
 	"previewProperties",
 	"readOnly",
+	"renderInForm",
 	"sortable",
 	"span",
 	"spreadChildren",
@@ -821,6 +895,7 @@ var policy = {
 		roles
 	}),
 	authenticated: () => ({ kind: "authenticated" }),
+	registered: () => ({ kind: "registered" }),
 	serverContext: () => ({ kind: "serverContext" }),
 	existsIn: (args) => ({
 		kind: "existsIn",
@@ -906,6 +981,17 @@ var REBASE_SCHEMA = "rebase";
 var RLS_UID_SQL = `${REBASE_SCHEMA}.uid()`;
 /** The request's roles as a comma-separated string, for `string_to_array`. */
 var RLS_ROLES_SQL = `${REBASE_SCHEMA}.roles()`;
+/**
+* Whether the caller is a GUEST — signed in through anonymous sign-in rather
+* than with an account.
+*
+* A different question from {@link ANONYMOUS_USER_ID}, and the two are easy to
+* confuse: that sentinel means "no session at all", while this means "a session
+* with nobody behind it". Anonymous sign-in mints a real user row with a real
+* uid, so before this reached the database the two kinds of caller were one
+* principal inside every policy.
+*/
+var RLS_IS_ANONYMOUS_SQL = `${REBASE_SCHEMA}.is_anonymous()`;
 /** The request's JWT claims as `jsonb`, or `{}`. */
 var RLS_JWT_SQL = `${REBASE_SCHEMA}.jwt()`;
 /**
@@ -1015,36 +1101,170 @@ function isResourceHandle(value) {
 function resourceKeyOf(ref) {
 	return isResourceHandle(ref) ? ref.key : ref;
 }
+/**
+* Replace every resource handle inside a value with its key, deeply.
+*
+* Applied where authored config becomes data: `defineCollection`, the
+* collection loaders, the derive step. Past that point a collection is plain
+* data that serialises, compares with `===` and reaches the admin UI over the
+* wire, so a handle must not survive into it. Plain objects and arrays are
+* walked; anything else — a function, a Date, a class instance — is a leaf and
+* is returned as it is, which is what keeps callbacks and validators intact.
+*/
+function resolveResourceRefs(value) {
+	if (isResourceHandle(value)) return value.key;
+	if (Array.isArray(value)) {
+		let changed = false;
+		const out = value.map((item) => {
+			const next = resolveResourceRefs(item);
+			if (next !== item) changed = true;
+			return next;
+		});
+		return changed ? out : value;
+	}
+	if (value !== null && typeof value === "object") {
+		const proto = Object.getPrototypeOf(value);
+		if (proto === Object.prototype || proto === null) {
+			let changed = false;
+			const out = {};
+			for (const [k, v] of Object.entries(value)) {
+				const next = resolveResourceRefs(v);
+				if (next !== v) changed = true;
+				out[k] = next;
+			}
+			return changed ? out : value;
+		}
+	}
+	return value;
+}
 var GLOBAL_KEY = Symbol.for("@rebasepro/types.resourceRegistry");
+/**
+* Where kinds live, versioned — and why the version is in the symbol.
+*
+* Sharing one kinds map across copies means the copy that registers SECOND is
+* the one that runs the comparison. That copy is whatever the bundle happens to
+* carry, which for a driver is a build of this package frozen at its release —
+* so the rule enforced is the rule that shipped THEN, not the one written here.
+*
+* `revision` (390bb03cd, applied to `database` in 346df48e2) was supposed to
+* settle a disagreement between two copies, and it settles it only when the
+* copy doing the arithmetic knows what `revision` is. 0.17.0–0.17.3 do not:
+* they deep-equal the spec and throw. The runtime registers at import and a
+* driver is imported after it, so the old copy is always second, always the
+* judge, and always throws — verified by the bundle corpus on 2026-09-07,
+* which reported v0.17.3's message verbatim ("Two packages cannot define the
+* same kind.", no revision clause) while the runtime it ran on was 0.18.
+*
+* So copies that understand `revision` keep their kinds here, under a symbol
+* no released copy looks at, and the legacy map is left to whoever still wants
+* it. An old copy then registers into a map nobody contests, finds no existing
+* entry, and cannot throw — in any load order, which is what the previous fix
+* only claimed. Bumping this suffix again is how a future change to the
+* REGISTRATION PROTOCOL is made; a change to a kind's own definition is still
+* `revision`, among peers that share this map.
+*/
+var KINDS_KEY = Symbol.for("@rebasepro/types.resourceKinds.v2");
 function registry() {
 	const g = globalThis;
-	let existing = g[GLOBAL_KEY];
-	if (!existing) {
-		existing = {
+	let shared = g[GLOBAL_KEY];
+	if (!shared) {
+		shared = {
 			kinds: /* @__PURE__ */ new Map(),
 			declarations: /* @__PURE__ */ new Map()
 		};
-		g[GLOBAL_KEY] = existing;
+		g[GLOBAL_KEY] = shared;
 	}
-	return existing;
+	let kinds = g[KINDS_KEY];
+	if (!kinds) {
+		kinds = /* @__PURE__ */ new Map();
+		g[KINDS_KEY] = kinds;
+	}
+	return {
+		kinds,
+		legacyKinds: shared.kinds,
+		declarations: shared.declarations
+	};
+}
+/**
+* Every kind visible to this copy: the versioned map, plus anything only a
+* legacy copy registered.
+*
+* The fallback is not for Rebase's own kinds — this copy defines all of those —
+* but for a third-party driver built against an older `@rebasepro/types` that
+* registers a kind of its own. Dropping it would make that kind invisible and
+* turn `declareResource` into "unknown resource kind" for something genuinely
+* registered.
+*/
+function visibleKinds() {
+	const { kinds, legacyKinds } = registry();
+	if (legacyKinds.size === 0) return kinds;
+	const merged = new Map(legacyKinds);
+	for (const [k, v] of kinds) merged.set(k, v);
+	return merged;
+}
+var amendments = /* @__PURE__ */ new Map();
+/**
+* Correct a registered kind without touching its registered literal.
+*
+* Use this, never an edit to the literal, for a kind that has shipped in a
+* published package. The amendment applies to reads through this copy only.
+*/
+function amendResourceKind(kind, amendment) {
+	amendments.set(kind, {
+		...amendments.get(kind),
+		...amendment
+	});
+}
+/** A registered kind as this copy sees it: the shared literal plus this copy's amendments. */
+function effectiveKind(spec) {
+	const amendment = amendments.get(spec.kind);
+	return amendment ? {
+		...spec,
+		...amendment
+	} : spec;
 }
 /** `kind:key`, the graph's primary key. */
 function declarationId(kind, key) {
 	return `${kind}:${key}`;
 }
-/** Register a resource kind. Idempotent for an identical spec; throws on a conflicting one. */
+/**
+* Register a resource kind.
+*
+* Idempotent for an identical spec. When a spec for the same kind is already
+* registered and differs, the `revision` decides: the higher one is kept and
+* the other copy is warned about, in either load order. Two different specs at
+* the SAME revision are a genuine conflict — two packages defining one kind, or
+* a change that forgot to bump — and still throw.
+*
+* Both copies in that comparison are peers on `KINDS_KEY`, which is what makes
+* the rule enforceable: a copy old enough not to know `revision` writes to the
+* legacy map instead and never reaches this function's arithmetic. Registering
+* a kind an older copy already put in the legacy map is therefore not a
+* conflict — it is the ordinary case, and `visibleKinds` prefers this one.
+*/
 function registerResourceKind(spec) {
-	const existing = registry().kinds.get(spec.kind);
-	if (existing && JSON.stringify(existing) !== JSON.stringify(spec)) throw new Error(`Resource kind "${spec.kind}" is already registered with a different definition. Two packages cannot define the same kind.`);
-	registry().kinds.set(spec.kind, spec);
+	const kinds = registry().kinds;
+	const existing = kinds.get(spec.kind);
+	if (!existing) {
+		kinds.set(spec.kind, spec);
+		return;
+	}
+	if (JSON.stringify(existing) === JSON.stringify(spec)) return;
+	const have = existing.revision ?? 0;
+	const incoming = spec.revision ?? 0;
+	if (have === incoming) throw new Error(`Resource kind "${spec.kind}" is already registered with a different definition at revision ${have}. Two packages cannot define the same kind; a newer definition of the same kind must carry a higher \`revision\`.`);
+	const [kept, dropped] = incoming > have ? [spec, existing] : [existing, spec];
+	if (kept === spec) kinds.set(spec.kind, spec);
+	console.warn(`[resources] Resource kind "${spec.kind}" is registered twice, at revisions ${dropped.revision ?? 0} and ${kept.revision ?? 0}; keeping revision ${kept.revision ?? 0}. The older copy is usually @rebasepro/types inlined in a driver built before the kind changed — rebuild the project with a current driver to remove it.`);
 }
 /** Every registered kind, for validators and for `rebase doctor`. */
 function resourceKinds() {
-	return [...registry().kinds.values()];
+	return [...visibleKinds().values()].map(effectiveKind);
 }
 /** One registered kind, or undefined. */
 function resourceKind(kind) {
-	return registry().kinds.get(kind);
+	const spec = visibleKinds().get(kind);
+	return spec && effectiveKind(spec);
 }
 var COMMON_OPTION_KEYS = [
 	"engine",
@@ -1065,9 +1285,9 @@ function isValidEngine(spec, engine) {
 * fine: a config module evaluated twice must not be an error.
 */
 function declareResource(kind, key = DEFAULT_RESOURCE_KEY, options = {}) {
-	const spec = registry().kinds.get(kind);
+	const spec = resourceKind(kind);
 	if (!spec) {
-		const known = [...registry().kinds.keys()].sort().join(", ") || "none";
+		const known = [...visibleKinds().keys()].sort().join(", ") || "none";
 		throw new Error(`Unknown resource kind "${kind}". Registered kinds: ${known}. Call registerResourceKind() before declaring one.`);
 	}
 	if (!key || typeof key !== "string" || key.trim() === "") throw new Error(`A ${kind} needs a non-empty key.`);
@@ -1149,13 +1369,29 @@ function findEnvSuffixCollision(keys) {
 }
 /** The current graph format version. */
 var RESOURCE_GRAPH_VERSION = 1;
-/** Build a graph from the current declarations, sorted for a stable diff. */
-function buildResourceGraph() {
+/**
+* Build a graph from the current declarations, sorted for a stable diff.
+*
+* `usedBy` maps a `kind:key` id to the things that reach it. The derive step
+* supplies it after evaluating collections; a runtime building the graph at
+* boot passes nothing and gets declarations alone, which is all it binds from.
+*/
+function buildResourceGraph(usedBy) {
 	return {
 		version: 1,
-		resources: declaredResources().slice().sort((a, b) => a.kind.localeCompare(b.kind) || a.key.localeCompare(b.key))
+		resources: declaredResources().slice().sort((a, b) => a.kind.localeCompare(b.kind) || a.key.localeCompare(b.key)).map((r) => {
+			const users = usedBy?.get(declarationId(r.kind, r.key));
+			return users && users.length > 0 ? {
+				...r,
+				usedBy: [...users].sort()
+			} : r;
+		})
 	};
 }
+/** `kind:key`, the id `usedBy` maps are keyed by. Exported for the derive step. */
+function resourceId(kind, key) {
+	return declarationId(kind, key);
+}
 /**
 * The environment variables worth writing for a resource, given its engine.
 *
@@ -1169,6 +1405,78 @@ function envBasesForResource(declaration) {
 	return spec.envBasesByEngine?.[declaration.engine] ?? spec.envBases;
 }
 //#endregion
+//#region src/types/storage_source.ts
+/**
+* Describes a named storage backend — a place files live.
+*
+* Declared once and shared front + back: the frontend uses it to decide
+* transport (HTTP proxy vs direct SDK), the backend uses the same `key`
+* to resolve a StorageController, and collection properties reference
+* a definition by its `key` via `StorageConfig.storageSource`.
+*
+* This mirrors the {@link DataSourceDefinition} pattern used for databases.
+*
+* @group Models
+*/
+/**
+* The default storage source key, used when a property does not specify
+* a `storageSource`. Shared by the frontend and backend registries so
+* both agree on "the default storage backend".
+* @group Models
+*/
+var DEFAULT_STORAGE_SOURCE_KEY = "(default)";
+/**
+* The environment-variable suffix for a storage or data source key.
+*
+* `""` for the default source — so a single-bucket project keeps configuring
+* plain `S3_BUCKET` — and `__<KEY>` for every named one, uppercased with
+* non-alphanumerics collapsed to underscores: `media-cdn` → `S3_BUCKET__MEDIA_CDN`.
+*
+* The rule derives the variable name from the declared key rather than
+* discovering keys by scanning the environment. Scanning would have to guess how
+* `S3_BUCKET__MEDIA_CDN` splits into a key; deriving cannot be ambiguous, and a
+* typo surfaces as a missing source at boot instead of a silently ignored
+* variable.
+*
+* It lives in this package, with no dependencies, because four things must agree
+* on it exactly: the CLI (validating a build), the runtime (reading its own
+* environment), the control plane (writing a tenant's Secret), and the docs. A
+* second implementation of a naming convention is a second chance to disagree.
+*
+* @group Models
+*/
+function storageEnvSuffix(key, defaultKey = DEFAULT_STORAGE_SOURCE_KEY) {
+	if (!key || key === defaultKey) return "";
+	const normalized = key.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "").toUpperCase();
+	if (!normalized) throw new Error(`Source key "${key}" cannot be turned into an environment variable name. Use a key containing at least one letter or digit.`);
+	return `__${normalized}`;
+}
+/**
+* Two distinct keys that collapse onto the same variable name, or `null`.
+*
+* `media-cdn` and `media_cdn` are different source keys but the same suffix, so
+* without this one of them silently reads the other's configuration. Returns the
+* offending pair rather than throwing, so each caller can raise it in its own
+* idiom — a `BundleError` at boot, a build failure in the CLI, a rejected deploy
+* in a control plane.
+*
+* @group Models
+*/
+function findStorageSuffixCollision(keys, defaultKey = DEFAULT_STORAGE_SOURCE_KEY) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const key of keys) {
+		const suffix = storageEnvSuffix(key, defaultKey);
+		const existing = seen.get(suffix);
+		if (existing !== void 0 && existing !== key) return {
+			a: existing,
+			b: key,
+			suffix
+		};
+		seen.set(suffix, key);
+	}
+	return null;
+}
+//#endregion
 //#region src/types/resource_kinds.ts
 /**
 * The kinds Rebase ships, and the constructors a project declares them with.
@@ -1184,6 +1492,7 @@ function envBasesForResource(declaration) {
 * instead of looking like a typo of one that exists.
 */
 registerResourceKind({
+	revision: 1,
 	kind: "database",
 	engines: [
 		"postgres",
@@ -1204,6 +1513,15 @@ registerResourceKind({
 	],
 	implicitDefault: true
 });
+amendResourceKind("database", { envBases: [
+	"DATABASE_URL",
+	"DATABASE_READ_URL",
+	"ADMIN_CONNECTION_STRING",
+	"REBASE_DRIVER",
+	"DB_POOL_MAX",
+	"DB_POOL_IDLE_TIMEOUT",
+	"DB_POOL_CONNECT_TIMEOUT"
+] });
 function database(keyOrOptions = DEFAULT_RESOURCE_KEY, options = {}) {
 	return typeof keyOrOptions === "string" ? declareResource("database", keyOrOptions, options) : declareResource("database", DEFAULT_RESOURCE_KEY, keyOrOptions);
 }
@@ -1263,18 +1581,49 @@ registerResourceKind({
 	],
 	implicitDefault: false
 });
-/**
-* Declare a bucket.
-*
-* ```ts
-* export const media = bucket("media", { transport: "direct" });
-* ```
-*
-* `transport: "direct"` means a provider SDK talks to the bucket and the
-* backend is not in the upload path.
-*/
-function bucket(key = DEFAULT_RESOURCE_KEY, options = {}) {
-	return declareResource("bucket", key, options);
+amendResourceKind("bucket", {
+	optionKeys: [
+		"publicRead",
+		"prefix",
+		"account",
+		"default"
+	],
+	envBases: [
+		"STORAGE_TYPE",
+		"STORAGE_PATH",
+		"S3_BUCKET",
+		"S3_REGION",
+		"S3_ACCESS_KEY_ID",
+		"S3_SECRET_ACCESS_KEY",
+		"S3_ENDPOINT",
+		"S3_FORCE_PATH_STYLE",
+		"GCS_BUCKET",
+		"GCS_PROJECT_ID",
+		"GCS_KEY_FILENAME"
+	],
+	envBasesByEngine: {
+		local: ["STORAGE_TYPE", "STORAGE_PATH"],
+		s3: [
+			"STORAGE_TYPE",
+			"S3_BUCKET",
+			"S3_REGION",
+			"S3_ACCESS_KEY_ID",
+			"S3_SECRET_ACCESS_KEY",
+			"S3_ENDPOINT",
+			"S3_FORCE_PATH_STYLE"
+		],
+		gcs: [
+			"STORAGE_TYPE",
+			"GCS_BUCKET",
+			"GCS_PROJECT_ID",
+			"GCS_KEY_FILENAME"
+		],
+		azure: [],
+		firebase: []
+	}
+});
+function bucket(keyOrOptions = DEFAULT_RESOURCE_KEY, options = {}) {
+	return typeof keyOrOptions === "string" ? declareResource("bucket", keyOrOptions, options) : declareResource("bucket", DEFAULT_RESOURCE_KEY, keyOrOptions);
 }
 registerResourceKind({
 	kind: "topic",
@@ -1284,6 +1633,7 @@ registerResourceKind({
 	optionKeys: ["delivery", "maxAttempts"],
 	implicitDefault: false
 });
+amendResourceKind("topic", { envBases: [] });
 var runtimeHolder = { current: null };
 /** Install the transport topics publish through. Called by the server at boot. */
 function setTopicRuntime(runtime) {
@@ -1331,10 +1681,145 @@ function topic(key, options = {}) {
 		}
 	};
 }
+registerResourceKind({
+	kind: "cron",
+	engines: ["scheduler"],
+	defaultEngine: "scheduler",
+	envBases: [],
+	optionKeys: [
+		"schedule",
+		"timezone",
+		"description",
+		"enabled",
+		"timeoutSeconds",
+		"catchUpWindowSeconds"
+	],
+	implicitDefault: false
+});
+/**
+* Declare a cron, as the scheduler's `defineCron` does on its way through.
+*
+* Projects do not call this: `defineCron` in `@rebasepro/server` does, so a
+* cron file is both the handler and the declaration — one file, one name, and
+* the graph derived from it says what a host needs to know without evaluating
+* the handler. Exported so the derive step and the scheduler spell the
+* declaration identically.
+*/
+function declareCron(name, options) {
+	if (typeof options.schedule !== "string" || options.schedule.trim() === "") throw new Error(`Cron "${name}" needs a schedule — a five-field cron expression such as "0 3 * * *".`);
+	return declareResource("cron", name, options);
+}
+registerResourceKind({
+	kind: "function",
+	engines: ["http"],
+	defaultEngine: "http",
+	envBases: [],
+	optionKeys: [
+		"portable",
+		"requires",
+		"file"
+	],
+	implicitDefault: false
+});
+/** Declare a function. Called by the derive step, not by projects. */
+function declareFunction(name, options = {}) {
+	return declareResource("function", name, options);
+}
+registerResourceKind({
+	kind: "queue",
+	engines: ["jobs"],
+	defaultEngine: "jobs",
+	envBases: [],
+	optionKeys: ["maxAttempts"],
+	implicitDefault: false
+});
+var queueRuntimeHolder = { current: null };
+/** Install the transport queues enqueue through. Called by the server at boot. */
+function setQueueRuntime(runtime) {
+	queueRuntimeHolder.current = runtime;
+}
+var queueConsumers = /* @__PURE__ */ new Map();
+/** Every declared queue handler, for the worker to wire. */
+function declaredQueueConsumers() {
+	return [...queueConsumers.values()];
+}
+/** Forget declared queue handlers. For tests, alongside `resetDeclaredResources`. */
+function resetDeclaredQueueConsumers() {
+	queueConsumers.clear();
+}
+/**
+* Declare a queue.
+*
+* ```ts
+* export const thumbnails = queue<{ key: string }>("thumbnails");
+* thumbnails.handler(async ({ key }) => { … });
+* await thumbnails.enqueue({ key }, { runAt: new Date(Date.now() + 60_000) });
+* ```
+*
+* The difference from a topic is the number of consumers: a queue has one, a
+* topic fans out to every subscription. Both ride on the durable job queue, so
+* declaring either turns it on.
+*/
+function queue(key, options = {}) {
+	return {
+		...declareResource("queue", key, options),
+		toString() {
+			return key;
+		},
+		async enqueue(payload, enqueueOptions) {
+			const runtime = queueRuntimeHolder.current;
+			if (!runtime) throw new Error(`Cannot enqueue on queue "${key}": no queue runtime is installed. Enqueueing works inside a running Rebase backend; this looks like config being evaluated outside one (a build, a script, or a test without a harness).`);
+			return runtime.enqueue(key, payload, enqueueOptions);
+		},
+		handler(fn) {
+			if (queueConsumers.has(key)) throw new Error(`Queue "${key}" already has a handler. A queue has exactly one consumer; work that several things react to is a topic with several subscriptions.`);
+			queueConsumers.set(key, {
+				queue: key,
+				handler: fn
+			});
+		}
+	};
+}
+/**
+* One declaration, as the data layer's definition.
+*
+* There is exactly one of these per kind, and everything that needs a
+* definition goes through it — the frontend, the managed runtime's boot path,
+* and an ejected project's own entrypoint. That is not tidiness: the mapping
+* used to exist twice, once here and once in `@rebasepro/server`'s
+* `graphToStorageSources`, and the two disagreed. The server's copy carried a
+* bucket's `account`; this one dropped it, so a bucket declared with shared
+* credentials resolved them on the managed runtime and resolved *nothing* in an
+* ejected backend — the source was skipped and every upload to it answered 501.
+*
+* A field-by-field map is one line away from that failure at all times, so
+* there is now one line to keep right instead of two to keep equal.
+*/
+function resourceToDataSource(declaration) {
+	return {
+		key: declaration.key === "(default)" ? DEFAULT_DATA_SOURCE_KEY : declaration.key,
+		engine: declaration.engine,
+		transport: declaration.transport,
+		...typeof declaration.options.databaseId === "string" ? { databaseId: declaration.options.databaseId } : {},
+		...declaration.label !== void 0 ? { label: declaration.label } : {}
+	};
+}
+/** One declaration, as the storage layer's definition. See {@link resourceToDataSource}. */
+function resourceToStorageSource(declaration) {
+	return {
+		key: declaration.key === "(default)" ? DEFAULT_STORAGE_SOURCE_KEY : declaration.key,
+		engine: declaration.engine,
+		transport: declaration.transport,
+		...typeof declaration.options.account === "string" ? { account: declaration.options.account } : {},
+		...declaration.options.default === true ? { default: true } : {},
+		...declaration.label !== void 0 ? { label: declaration.label } : {}
+	};
+}
 /**
-* The declared databases, in the shape `<Rebase dataSources>` takes.
+* The declared databases, as definitions.
 *
-* The frontend needs to know which sources exist and how they are reached — a
+* Both the frontend and a project's own backend entrypoint read this. The
+* frontend needs to know which sources exist and how they are reached — a
 * `direct`-transport source is one the browser talks to itself — and it imports
 * the same config package the backend does. Without these it would mean writing
 * the list a second time, by hand, next to the declarations, which is precisely
@@ -1352,134 +1837,11 @@ function topic(key, options = {}) {
 * bare re-export.
 */
 function declaredDataSources() {
-	return declaredResources("database").map((r) => ({
-		key: r.key,
-		engine: r.engine,
-		transport: r.transport,
-		...r.label !== void 0 ? { label: r.label } : {}
-	}));
-}
-/** The declared buckets, in the shape `<Rebase storageSources>` takes. */
-function declaredStorageSources() {
-	return declaredResources("bucket").map((r) => ({
-		key: r.key,
-		engine: r.engine,
-		transport: r.transport,
-		...r.label !== void 0 ? { label: r.label } : {}
-	}));
+	return declaredResources("database").map(resourceToDataSource);
 }
-//#endregion
-//#region src/types/storage_source.ts
-/**
-* Describes a named storage backend — a place files live.
-*
-* Declared once and shared front + back: the frontend uses it to decide
-* transport (HTTP proxy vs direct SDK), the backend uses the same `key`
-* to resolve a StorageController, and collection properties reference
-* a definition by its `key` via `StorageConfig.storageSource`.
-*
-* This mirrors the {@link DataSourceDefinition} pattern used for databases.
-*
-* @group Models
-*/
-/**
-* The default storage source key, used when a property does not specify
-* a `storageSource`. Shared by the frontend and backend registries so
-* both agree on "the default storage backend".
-* @group Models
-*/
-var DEFAULT_STORAGE_SOURCE_KEY = "(default)";
-/**
-* The environment-variable suffix for a storage or data source key.
-*
-* `""` for the default source — so a single-bucket project keeps configuring
-* plain `S3_BUCKET` — and `__<KEY>` for every named one, uppercased with
-* non-alphanumerics collapsed to underscores: `media-cdn` → `S3_BUCKET__MEDIA_CDN`.
-*
-* The rule derives the variable name from the declared key rather than
-* discovering keys by scanning the environment. Scanning would have to guess how
-* `S3_BUCKET__MEDIA_CDN` splits into a key; deriving cannot be ambiguous, and a
-* typo surfaces as a missing source at boot instead of a silently ignored
-* variable.
-*
-* It lives in this package, with no dependencies, because four things must agree
-* on it exactly: the CLI (validating a build), the runtime (reading its own
-* environment), the control plane (writing a tenant's Secret), and the docs. A
-* second implementation of a naming convention is a second chance to disagree.
-*
-* @group Models
-*/
-function storageEnvSuffix(key, defaultKey = DEFAULT_STORAGE_SOURCE_KEY) {
-	if (!key || key === defaultKey) return "";
-	const normalized = key.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "").toUpperCase();
-	if (!normalized) throw new Error(`Source key "${key}" cannot be turned into an environment variable name. Use a key containing at least one letter or digit.`);
-	return `__${normalized}`;
-}
-/**
-* Two distinct keys that collapse onto the same variable name, or `null`.
-*
-* `media-cdn` and `media_cdn` are different source keys but the same suffix, so
-* without this one of them silently reads the other's configuration. Returns the
-* offending pair rather than throwing, so each caller can raise it in its own
-* idiom — a `BundleError` at boot, a build failure in the CLI, a rejected deploy
-* in a control plane.
-*
-* @group Models
-*/
-function findStorageSuffixCollision(keys, defaultKey = DEFAULT_STORAGE_SOURCE_KEY) {
-	const seen = /* @__PURE__ */ new Map();
-	for (const key of keys) {
-		const suffix = storageEnvSuffix(key, defaultKey);
-		const existing = seen.get(suffix);
-		if (existing !== void 0 && existing !== key) return {
-			a: existing,
-			b: key,
-			suffix
-		};
-		seen.set(suffix, key);
-	}
-	return null;
-}
-/**
-* Merge the two places a project may declare storage sources into one list.
-*
-* `rebase.json` is authoritative for every field it states. Config code may add
-* sources it does not mention and fill in fields it left out, but may not
-* contradict it: the manifest is what a host reads to decide which buckets need
-* configuring, and a runtime that quietly disagreed with it would put the
-* console back to describing a topology the tenant does not have — the exact
-* failure this whole mechanism exists to end.
-*
-* Note what is *not* here: no default source is invented when both inputs are
-* empty. That decision belongs to the resolver, which knows whether declaring
-* nothing means "one plain bucket" (it does) or "no storage at all".
-*
-* @group Models
-*/
-function normalizeStorageSources(declared, exported) {
-	const merged = /* @__PURE__ */ new Map();
-	const declaredEntries = Array.isArray(declared) ? declared.filter((d) => d?.key).map((d) => [d.key, d]) : Object.entries(declared ?? {});
-	for (const [key, config] of declaredEntries) merged.set(key, {
-		key,
-		engine: config.engine,
-		transport: config.transport ?? "server",
-		...config.label !== void 0 ? { label: config.label } : {}
-	});
-	for (const definition of exported ?? []) {
-		if (!definition?.key) continue;
-		const existing = merged.get(definition.key);
-		if (!existing) {
-			merged.set(definition.key, {
-				key: definition.key,
-				engine: definition.engine,
-				transport: definition.transport ?? "server",
-				...definition.label !== void 0 ? { label: definition.label } : {}
-			});
-			continue;
-		}
-		if (existing.label === void 0 && definition.label !== void 0) existing.label = definition.label;
-	}
-	return Array.from(merged.values());
+/** The declared buckets, as definitions. */
+function declaredStorageSources() {
+	return declaredResources("bucket").map(resourceToStorageSource);
 }
 //#endregion
 //#region src/types/component_ref.ts
@@ -1893,6 +2255,6 @@ function isPublicStoragePath(path) {
 	return p.startsWith("public/") || p.startsWith(`default/public/`);
 }
 //#endregion
-export { ADMIN_COLLECTION_KEYS, ADMIN_PROPERTY_KEYS, ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, BUNDLE_FORMAT_VERSION, CANONICAL_TO_REST, DEFAULT_CAPABILITIES, DEFAULT_COMMIT_PATHS, DEFAULT_DATA_SOURCE_KEY, DEFAULT_FILTERABLE_RELATION_KINDS, DEFAULT_FUZZY_THRESHOLD, DEFAULT_LIST_LIMIT, DEFAULT_RESOURCE_KEY, DEFAULT_SEARCH_COLUMN, DEFAULT_SEARCH_LANGUAGE, DEFAULT_SEARCH_WEIGHT, DEFAULT_STORAGE_SOURCE_KEY, DEFAULT_VECTOR_LIST_LIMIT, EntityReference, EntityRelation, FIREBASE_CAPABILITIES, GeoPoint, LEGACY_RLS_JWT_SQL, LEGACY_RLS_ROLES_SQL, LEGACY_RLS_SCHEMA, LEGACY_RLS_UID_SQL, ListLimitError, MAX_LIST_LIMIT, MONGODB_CAPABILITIES, NULL_OPS, POSTGRES_CAPABILITIES, PUBLIC_STORAGE_PREFIX, REBASE_SCHEMA, RELEVANCE_SORT_FIELD, RESERVED_BACKEND_PREFIXES, RESOURCE_GRAPH_VERSION, REST_TO_CANONICAL, RLS_JWT_SQL, RLS_ROLES_SQL, RLS_UID_SQL, RUNTIME_CONTRACT_VERSION, RebaseApiError, RebaseClientError, SCHEMA_VERSION_HEADER, Vector, bucket, buildResourceGraph, canonicalSchemaPayload, computeSchemaVersion, database, declareResource, declaredDataSources, declaredDatabaseExtensions, declaredResources, declaredStorageSources, declaredSubscriptions, deserializeCollections, encodeRelationAggregateSort, envBasesForResource, findEnvSuffixCollision, findStorageSuffixCollision, getCollectionDataPath, getDataSourceCapabilities, getDeclaredSubcollections, hasForeignKeyOnTarget, isAnonymousUid, isBranchAdmin, isChannelBusInstance, isDocumentAdmin, isFirebaseCollectionConfig, isLazyComponentRef, isManyToMany, isMongoDBCollectionConfig, isPostgresCollectionConfig, isPublicStoragePath, isRelationAggregateSort, isRelationalCollectionConfig, isResourceHandle, isSQLAdmin, isSchemaAdmin, isSchemaEditingAdmin, isSerializedCollectionRef, isToMany, isValidEngine, nestAdminCollectionKeys, nestAdminKeysOf, nestAdminPropertyKeys, normalizeStorageSources, parseRelationAggregateSort, policy, registerDataSourceCapabilities, registerResourceKind, reservedPrefixFor, resetDeclaredResources, resetDeclaredSubscriptions, resolveClientListLimit, resourceEnvSuffix, resourceKeyOf, resourceKind, resourceKinds, rewriteLegacyRlsFunctions, serializeCollections, setTopicRuntime, sortKeyToString, storageEnvSuffix, toCanonicalOp, topic, usesLegacyRlsFunctions };
+export { ADMIN_COLLECTION_KEYS, ADMIN_PROPERTY_KEYS, ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, BUNDLE_FORMAT_VERSION, CANONICAL_TO_REST, DEFAULT_CAPABILITIES, DEFAULT_COMMIT_PATHS, DEFAULT_DATA_SOURCE_KEY, DEFAULT_FILTERABLE_RELATION_KINDS, DEFAULT_FUZZY_THRESHOLD, DEFAULT_LIST_LIMIT, DEFAULT_RESOURCE_KEY, DEFAULT_SEARCH_COLUMN, DEFAULT_SEARCH_LANGUAGE, DEFAULT_SEARCH_WEIGHT, DEFAULT_STORAGE_SOURCE_KEY, DEFAULT_VECTOR_LIST_LIMIT, EntityReference, EntityRelation, FIREBASE_CAPABILITIES, GeoPoint, LEGACY_RLS_JWT_SQL, LEGACY_RLS_ROLES_SQL, LEGACY_RLS_SCHEMA, LEGACY_RLS_UID_SQL, ListLimitError, MAX_LIST_LIMIT, MONGODB_CAPABILITIES, NULL_OPS, POSTGRES_CAPABILITIES, PUBLIC_STORAGE_PREFIX, REBASE_SCHEMA, RELEVANCE_SORT_FIELD, RESERVED_BACKEND_PREFIXES, RESOURCE_GRAPH_VERSION, REST_TO_CANONICAL, RLS_IS_ANONYMOUS_SQL, RLS_JWT_SQL, RLS_ROLES_SQL, RLS_UID_SQL, RUNTIME_CONTRACT_VERSION, RebaseApiError, RebaseClientError, SCHEMA_VERSION_HEADER, Vector, amendResourceKind, bucket, buildResourceGraph, canonicalSchemaPayload, computeSchemaVersion, database, declareCron, declareFunction, declareResource, declaredDataSources, declaredDatabaseExtensions, declaredQueueConsumers, declaredResources, declaredStorageSources, declaredSubscriptions, deserializeCollections, encodeRelationAggregateSort, envBasesForResource, findEnvSuffixCollision, findStorageSuffixCollision, getCollectionDataPath, getDataSourceCapabilities, getDeclaredSubcollections, hasForeignKeyOnTarget, isAnonymousUid, isBranchAdmin, isChannelBusInstance, isDocumentAdmin, isFirebaseCollectionConfig, isLazyComponentRef, isManyToMany, isMongoDBCollectionConfig, isPostgresCollectionConfig, isPublicStoragePath, isRelationAggregateSort, isRelationalCollectionConfig, isResourceHandle, isSQLAdmin, isSchemaAdmin, isSchemaEditingAdmin, isSerializedCollectionRef, isToMany, isUnsupported, isValidEngine, nestAdminCollectionKeys, nestAdminKeysOf, nestAdminPropertyKeys, parseRelationAggregateSort, policy, queue, registerDataSourceCapabilities, registerResourceKind, reservedPrefixFor, resetDeclaredQueueConsumers, resetDeclaredResources, resetDeclaredSubscriptions, resolveClientListLimit, resolveResourceRefs, resourceEnvSuffix, resourceId, resourceKeyOf, resourceKind, resourceKinds, resourceToDataSource, resourceToStorageSource, rewriteLegacyRlsFunctions, serializeCollections, setQueueRuntime, setTopicRuntime, sortKeyToString, storageEnvSuffix, toCanonicalOp, topic, unsupportedMethod, usesLegacyRlsFunctions };
 
 //# sourceMappingURL=index.es.js.map