@rebasepro/types 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/index.es.js

@@ -499,6 +499,7 @@ var ADMIN_PROPERTY_KEYS = [
 	"disabled",
 	"expanded",
 	"Field",
+	"filledByServer",
 	"Filter",
 	"filterOperators",
 	"fixedFilter",
@@ -700,12 +701,29 @@ var DEFAULT_CAPABILITIES = {
 	supportsDocumentAdmin: true,
 	supportsSchemaAdmin: true
 };
-var CAPABILITIES_REGISTRY = {
-	postgres: POSTGRES_CAPABILITIES,
-	firestore: FIREBASE_CAPABILITIES,
-	mongodb: MONGODB_CAPABILITIES,
-	"(default)": DEFAULT_CAPABILITIES
-};
+var BUILT_IN_CAPABILITIES = /* @__PURE__ */ new Map([
+	["postgres", POSTGRES_CAPABILITIES],
+	["firestore", FIREBASE_CAPABILITIES],
+	["mongodb", MONGODB_CAPABILITIES],
+	["(default)", DEFAULT_CAPABILITIES]
+]);
+/**
+* Capabilities registered at runtime, on `globalThis` rather than in a module
+* local: a third-party driver inlines its own copy of this package and
+* registers through it, while the app and the server read through theirs. A
+* module local made the registration land in a copy nobody else reads.
+* See `module-state-across-copies.test.ts`.
+*/
+var REGISTERED_CAPABILITIES_KEY = Symbol.for("@rebasepro/types.dataSourceCapabilities.v1");
+function registeredCapabilities() {
+	const g = globalThis;
+	let registered = g[REGISTERED_CAPABILITIES_KEY];
+	if (!registered) {
+		registered = /* @__PURE__ */ new Map();
+		g[REGISTERED_CAPABILITIES_KEY] = registered;
+	}
+	return registered;
+}
 /**
 * Look up capabilities for a given engine key.
 * If `engine` is undefined or not found, returns `DEFAULT_CAPABILITIES`.
@@ -713,14 +731,14 @@ var CAPABILITIES_REGISTRY = {
 */
 function getDataSourceCapabilities(engine) {
 	if (!engine) return POSTGRES_CAPABILITIES;
-	return CAPABILITIES_REGISTRY[engine] ?? DEFAULT_CAPABILITIES;
+	return registeredCapabilities().get(engine) ?? BUILT_IN_CAPABILITIES.get(engine) ?? DEFAULT_CAPABILITIES;
 }
 /**
 * Register custom capabilities for a third-party driver.
 * @group Models
 */
 function registerDataSourceCapabilities(capabilities) {
-	CAPABILITIES_REGISTRY[capabilities.key] = capabilities;
+	registeredCapabilities().set(capabilities.key, capabilities);
 }
 //#endregion
 //#region src/types/collections.ts
@@ -837,6 +855,23 @@ var RELEVANCE_SORT_FIELD = "_score";
 * @group Models
 */
 var JUNCTION_PIVOT_KEY = "_pivot";
+/**
+* The key a row carries the totals of its counted relations under.
+*
+* An include that asks for a count — `include: { tags: { limit: 4, count: true } }`
+* — serves, beside the (capped) `tags`, how many related rows there are in all:
+* `{ id: 1, tags: [ …4 rows ], _count: { tags: 37 } }`. One object per row,
+* keyed by relation name, so counting a second relation adds a key rather than
+* a second top-level name.
+*
+* Leading underscore, like {@link JUNCTION_PIVOT_KEY} and `_matches`: it
+* describes the read, not the record, and no column or form writes it. A
+* collection with a property of this name cannot ask for a count — the read
+* answers 400 rather than writing over the column.
+*
+* @group Models
+*/
+var INCLUDE_COUNT_KEY = "_count";
 /** @group Models */
 function hasForeignKeyOnTarget(relation) {
 	return relation.kind === "hasOne" || relation.kind === "hasMany";
@@ -1131,14 +1166,281 @@ function isBranchAdmin(admin) {
 }
 //#endregion
 //#region src/types/schema_editing.ts
-var DEFAULT_COMMIT_PATHS = {
-	schemaFile: "backend/src/schema.generated.ts",
-	ddlFile: "drizzle/schema.sql",
-	policiesFile: "drizzle/policies.sql",
-	searchFile: "drizzle/search.sql",
-	vectorFile: "drizzle/vector.sql",
-	triggersFile: "drizzle/triggers.sql"
-};
+/**
+* The SQL `db push` and `db generate` render — `schema.sql`, `policies.sql` and
+* the rest — is not here, and must not come back. Both commands regenerate it
+* from the collections before reading it, so nothing ever read a committed
+* copy; it lives in the gitignored `.rebase/sql/`. When the commit carried it,
+* it carried a second copy besides: these paths are from the project root,
+* while the CLI writes beside the backend, so a live edit left `drizzle/` and
+* `backend/drizzle/` disagreeing about the schema.
+*/
+var DEFAULT_COMMIT_PATHS = { schemaFile: "backend/src/schema.generated.ts" };
+//#endregion
+//#region src/types/collection_patch.ts
+/**
+* What changed about a collection, as opposed to what the collection is.
+*
+* ## Why a save is a patch
+*
+* The admin panel edits a collection as JSON — the only form a browser and a
+* server can exchange it in — and JSON cannot carry most of what a collection
+* file holds: an entity action's `onClick`, a computed field's `value`, a
+* property shared from another module (`status: statusProperty`), an enum
+* imported from elsewhere (`enum: LOCALE_ENUM`), the comments around all of
+* them. A save that posted the whole collection and had it written back
+* rewrote every key it carried and deleted everything JSON had dropped, so
+* renaming a collection removed its actions' handlers, inlined its shared
+* property without the custom `Field`, and froze a copy of the enum.
+*
+* So a save sends what the person changed: the difference between the JSON
+* the editor loaded and the JSON it is saving. Anything JSON could not carry
+* is identical on both sides of that difference — dropped from both — and
+* cannot appear in it. The server applies the patch to the collection as it
+* is (for the plan) and writes only the patched keys into the file.
+*
+* ## The shape
+*
+* Two operations on paths of object keys. Arrays are values: an array that
+* changed is set whole. Positions in an array are not stable identities —
+* element 2 of an enum is not "the third value" once a value is inserted —
+* and the writer is the one place that can match an old element to its new
+* self (by `key`/`id`/`name`) and keep what JSON dropped from it.
+*
+* Paths are in the AUTHORING shape — presentation keys under `admin`, the
+* shape the file has — see {@link nestCollectionPatchPaths}.
+*/
+/**
+* Keys the runtime adds to a collection that must never be written into its
+* source. `resolvedRelation` is the registry's resolved form of a relation; a
+* file holding one does not type-check (`target` is missing from it).
+*/
+var RUNTIME_ONLY_COLLECTION_KEYS = ["resolvedRelation"];
+/** Path segments that reach an object's prototype rather than a key of it. */
+var UNSAFE_SEGMENTS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+var isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A JSON value as JSON would carry it: functions, `undefined` and symbols dropped. */
+function toCollectionJson(value) {
+	if (value === void 0) return void 0;
+	const text = JSON.stringify(value);
+	return text === void 0 ? void 0 : JSON.parse(text);
+}
+function jsonEqual(a, b) {
+	if (a === b) return true;
+	if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((item, index) => jsonEqual(item, b[index]));
+	if (isPlainObject(a) && isPlainObject(b)) {
+		const keys = Object.keys(a);
+		if (keys.length !== Object.keys(b).length) return false;
+		return keys.every((key) => Object.prototype.hasOwnProperty.call(b, key) && jsonEqual(a[key], b[key]));
+	}
+	return false;
+}
+/**
+* The operations that take `before` to `after`, both JSON values.
+*
+* Objects are compared key by key; anything else that differs — a primitive,
+* an array, a change of kind — is set whole.
+*/
+function diffJsonValues(before, after, path = []) {
+	if (jsonEqual(before, after)) return [];
+	if (isPlainObject(before) && isPlainObject(after)) {
+		const ops = [];
+		for (const key of Object.keys(after)) if (!Object.prototype.hasOwnProperty.call(before, key)) ops.push({
+			op: "set",
+			path: [...path, key],
+			value: after[key]
+		});
+		else ops.push(...diffJsonValues(before[key], after[key], [...path, key]));
+		for (const key of Object.keys(before)) if (!Object.prototype.hasOwnProperty.call(after, key)) ops.push({
+			op: "remove",
+			path: [...path, key]
+		});
+		return ops;
+	}
+	return [{
+		op: "set",
+		path,
+		value: after
+	}];
+}
+function step(position, segment) {
+	switch (position) {
+		case "collection": return segment === "properties" ? "properties" : "other";
+		case "properties": return "property";
+		case "property":
+			if (segment === "properties") return "properties";
+			if (segment === "of") return "property";
+			if (segment === "oneOf") return "oneOf";
+			return "other";
+		case "oneOf": return segment === "properties" ? "properties" : "other";
+		default: return "other";
+	}
+}
+function nestPath(path) {
+	const nested = [];
+	let position = "collection";
+	for (const segment of path) {
+		const moved = position === "collection" && ADMIN_COLLECTION_KEYS.includes(segment) || position === "property" && ADMIN_PROPERTY_KEYS.includes(segment);
+		if (moved) nested.push("admin");
+		nested.push(segment);
+		position = moved ? "other" : step(position, segment);
+	}
+	return {
+		path: nested,
+		position
+	};
+}
+function nestValue(position, value) {
+	if (position === "property") {
+		if (Array.isArray(value)) return value.map((entry) => isPlainObject(entry) ? nestAdminPropertyKeys(entry) : entry);
+		return isPlainObject(value) ? nestAdminPropertyKeys(value) : value;
+	}
+	if (position === "properties" && isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, property]) => [key, isPlainObject(property) ? nestAdminPropertyKeys(property) : property]));
+	if (position === "oneOf" && isPlainObject(value)) return isPlainObject(value.properties) ? {
+		...value,
+		properties: nestValue("properties", value.properties)
+	} : value;
+	if (position === "collection" && isPlainObject(value)) {
+		const nested = nestAdminCollectionKeys(value);
+		return isPlainObject(nested.properties) ? {
+			...nested,
+			properties: nestValue("properties", nested.properties)
+		} : nested;
+	}
+	return value;
+}
+/**
+* The patch, with every flat presentation key moved into its `admin` block.
+*
+* The panel edits a flat view model — `icon` beside `name`, a property's
+* `readOnly` beside its `type` — while the file keeps them under `admin`. The
+* difference is taken on the flat model, because that is where a cleared field
+* shows up as a removed key (the `admin` copy the model was loaded with still
+* holds the old value), and moved here.
+*
+* The flat value wins over the `admin` copy, as in {@link nestAdminKeysOf}:
+* operations that were already under `admin` are ordered first, so the flat
+* one — what the form just wrote — is applied last.
+*/
+function nestCollectionPatchPaths(patch) {
+	return patch.map((op, index) => {
+		const { path, position } = nestPath(op.path);
+		const wasNested = op.path.includes("admin");
+		return {
+			moved: op.op === "remove" ? {
+				op: "remove",
+				path
+			} : {
+				op: "set",
+				path,
+				value: nestValue(position, op.value)
+			},
+			wasNested,
+			index
+		};
+	}).sort((a, b) => a.wasNested === b.wasNested ? a.index - b.index : a.wasNested ? -1 : 1).map((entry) => entry.moved);
+}
+/**
+* The patch that takes the collection the editor loaded to the one it is
+* saving, in the authoring shape. Empty when nothing changed.
+*
+* Both sides go through JSON first, so whatever JSON cannot carry — a
+* function, a value it drops — is equally absent from both and never appears
+* as a change.
+*/
+function diffCollections(loaded, saving) {
+	return nestCollectionPatchPaths(diffJsonValues(toCollectionJson(loaded), toCollectionJson(saving)));
+}
+/**
+* Why a patch may not be applied, or an empty list.
+*
+* Checked by every door that accepts one: a path is a list of non-empty object
+* keys that cannot reach a prototype, and no runtime-only key may be written.
+*/
+function collectionPatchProblems(patch) {
+	if (!Array.isArray(patch)) return ["`patch` must be a list of operations."];
+	const problems = [];
+	patch.forEach((op, index) => {
+		const where = `patch[${index}]`;
+		if (!isPlainObject(op) || op.op !== "set" && op.op !== "remove") {
+			problems.push(`${where} must be { op: "set", path, value } or { op: "remove", path }.`);
+			return;
+		}
+		const path = op.path;
+		if (!Array.isArray(path) || path.length === 0 || !path.every((segment) => typeof segment === "string" && segment.length > 0)) {
+			problems.push(`${where}.path must be a non-empty list of object keys.`);
+			return;
+		}
+		const unsafe = path.find((segment) => UNSAFE_SEGMENTS.has(segment));
+		if (unsafe) problems.push(`${where}.path may not contain "${unsafe}".`);
+		const runtime = path.find((segment) => RUNTIME_ONLY_COLLECTION_KEYS.includes(segment));
+		if (runtime) problems.push(`${where} writes "${runtime}", which the runtime adds and a collection file must not hold.`);
+		if (op.op === "set") {
+			const key = keyIn(op.value, (key) => UNSAFE_SEGMENTS.has(key) || RUNTIME_ONLY_COLLECTION_KEYS.includes(key));
+			if (key) problems.push(`${where}.value holds "${key}", which a collection file must not hold.`);
+		}
+	});
+	return problems;
+}
+/**
+* The first runtime-only key (see {@link RUNTIME_ONLY_COLLECTION_KEYS}) found
+* anywhere in a value, or `undefined`. For the doors that take a whole
+* collection rather than a patch.
+*/
+function runtimeOnlyKeyIn(value) {
+	return keyIn(value, (key) => RUNTIME_ONLY_COLLECTION_KEYS.includes(key));
+}
+/** A patch every door may apply: {@link collectionPatchProblems} found nothing. */
+function isCollectionPatch(patch) {
+	return collectionPatchProblems(patch).length === 0;
+}
+function keyIn(value, matches) {
+	if (Array.isArray(value)) {
+		for (const item of value) {
+			const found = keyIn(item, matches);
+			if (found) return found;
+		}
+		return;
+	}
+	if (!isPlainObject(value)) return void 0;
+	for (const key of Object.keys(value)) {
+		if (matches(key)) return key;
+		const found = keyIn(value[key], matches);
+		if (found) return found;
+	}
+}
+/**
+* `target` with the patch applied, copying only what it changes.
+*
+* Everything the patch does not reach is shared with `target` by reference —
+* functions, thunks and all — which is what lets a planner see a relation's
+* `target()` on the patched collection exactly as it was. Intermediate objects
+* a `set` needs are created; a `remove` of a key that is not there is nothing
+* to do.
+*/
+function applyCollectionPatch(target, patch) {
+	let root = target;
+	for (const op of patch) root = applyOp(root, op.path, op);
+	return root;
+}
+function applyOp(node, path, op) {
+	const [head, ...rest] = path;
+	if (UNSAFE_SEGMENTS.has(head)) throw new Error(`A collection patch may not reach "${head}".`);
+	const base = isPlainObject(node) ? { ...node } : {};
+	if (rest.length === 0) {
+		if (op.op === "remove") delete base[head];
+		else base[head] = op.value;
+		return base;
+	}
+	const child = Object.prototype.hasOwnProperty.call(base, head) ? base[head] : void 0;
+	if (op.op === "remove" && !isPlainObject(child)) return node;
+	base[head] = applyOp(child, rest, op);
+	return base;
+}
 //#endregion
 //#region src/types/channel_bus.ts
 /**
@@ -1663,10 +1965,15 @@ amendResourceKind("bucket", {
 		"S3_FORCE_PATH_STYLE",
 		"GCS_BUCKET",
 		"GCS_PROJECT_ID",
-		"GCS_KEY_FILENAME"
+		"GCS_KEY_FILENAME",
+		"STORAGE_MAX_FILE_SIZE"
 	],
 	envBasesByEngine: {
-		local: ["STORAGE_TYPE", "STORAGE_PATH"],
+		local: [
+			"STORAGE_TYPE",
+			"STORAGE_PATH",
+			"STORAGE_MAX_FILE_SIZE"
+		],
 		s3: [
 			"STORAGE_TYPE",
 			"S3_BUCKET",
@@ -1674,13 +1981,15 @@ amendResourceKind("bucket", {
 			"S3_ACCESS_KEY_ID",
 			"S3_SECRET_ACCESS_KEY",
 			"S3_ENDPOINT",
-			"S3_FORCE_PATH_STYLE"
+			"S3_FORCE_PATH_STYLE",
+			"STORAGE_MAX_FILE_SIZE"
 		],
 		gcs: [
 			"STORAGE_TYPE",
 			"GCS_BUCKET",
 			"GCS_PROJECT_ID",
-			"GCS_KEY_FILENAME"
+			"GCS_KEY_FILENAME",
+			"STORAGE_MAX_FILE_SIZE"
 		],
 		azure: [],
 		firebase: []
@@ -1698,19 +2007,73 @@ registerResourceKind({
 	implicitDefault: false
 });
 amendResourceKind("topic", { envBases: [] });
-var runtimeHolder = { current: null };
+/**
+* Declared handlers and installed runtimes, for topics and queues — on
+* `globalThis` under a shared symbol, never in module locals.
+*
+* A module local is one per COPY of this package, and two copies in one
+* process is the normal layout rather than an accident: `@rebasepro/server`
+* inlines this package into its own dist, while `config/resources.ts` imports
+* it from `node_modules`. With locals, a project's `.handler()` and
+* `.subscription()` went into the project's copy and the worker read the
+* server's empty one (`Job queue started {"tasks":0}`), and the runtime the
+* server installed was invisible to the project's `enqueue`/`publish` — so
+* every queue and topic threw "no runtime is installed" inside a running
+* backend. The CLI deriving the graph had the same split. Same mechanism and
+* reasoning as `registry()` in resources.ts; `module-state-across-copies.test.ts`
+* loads two copies to hold it, and scans for any other module-level state that
+* would split the same way.
+*
+* The version is in the symbol: a change to this object's SHAPE takes a new
+* suffix, so no copy ever reads a shape it does not know.
+*/
+var WORK_KEY = Symbol.for("@rebasepro/types.workRegistry.v1");
+function work() {
+	const g = globalThis;
+	let shared = g[WORK_KEY];
+	if (!shared) {
+		shared = {
+			topicRuntime: null,
+			subscriptions: [],
+			queueRuntime: null,
+			queueConsumers: /* @__PURE__ */ new Map()
+		};
+		g[WORK_KEY] = shared;
+	}
+	return shared;
+}
+/**
+* Where `@rebasepro/server` publishes its client once it has booted (its
+* `singleton.ts`). Read only to tell the two causes of a missing runtime apart.
+*/
+var SERVER_INSTANCE_SLOT = Symbol.for("@rebasepro/server:singleton-instance");
+/**
+* Why there is no runtime to send through, as far as this process can tell.
+*
+* Outside a backend — the CLI evaluating config, a script, a unit test — the
+* answer is that there is nothing to deliver to. Inside one it is not: the
+* backend installs a runtime at boot for what `config/resources.ts` declared,
+* so a missing one there means boot never saw the declaration, or the backend
+* carries a copy of this package too old to share the slot it installs into.
+* Saying "outside a backend" to somebody whose backend is running sends them
+* looking for the wrong thing.
+*/
+function missingRuntimeCause(kind) {
+	if (!(globalThis[SERVER_INSTANCE_SLOT] != null)) return "This works inside a running Rebase backend; this looks like code running outside one (a build, a script, or a test without a harness).";
+	return `A Rebase backend is running in this process but installed no ${kind} runtime. It installs one at boot when config/resources.ts declares a ${kind}, so either this ${kind} is declared somewhere boot does not read, or the backend's copy of @rebasepro/types predates the shared runtime slot this copy reads — keep @rebasepro/server and @rebasepro/types on the same version.`;
+}
 /** Install the transport topics publish through. Called by the server at boot. */
 function setTopicRuntime(runtime) {
-	runtimeHolder.current = runtime;
+	work().topicRuntime = runtime;
 }
-var subscriptions = [];
 /** Every declared subscription, for the worker to wire and the graph to record. */
 function declaredSubscriptions(topic) {
+	const { subscriptions } = work();
 	return topic ? subscriptions.filter((s) => s.topic === topic) : subscriptions.slice();
 }
 /** Forget declared subscriptions. For tests, alongside `resetDeclaredResources`. */
 function resetDeclaredSubscriptions() {
-	subscriptions.length = 0;
+	work().subscriptions.length = 0;
 }
 /**
 * Declare a topic.
@@ -1729,12 +2092,13 @@ function topic(key, options = {}) {
 			return key;
 		},
 		async publish(event) {
-			const runtime = runtimeHolder.current;
-			if (!runtime) throw new Error(`Cannot publish to topic "${key}": no topic runtime is installed. Publishing works inside a running Rebase backend; this looks like config being evaluated outside one (a build, a script, or a test without a harness).`);
+			const runtime = work().topicRuntime;
+			if (!runtime) throw new Error(`Cannot publish to topic "${key}": no topic runtime is installed. ${missingRuntimeCause("topic")}`);
 			await runtime.publish(key, event);
 		},
 		subscription(name, handler, subOptions = {}) {
 			if (!name || name.trim() === "") throw new Error(`A subscription on topic "${key}" needs a non-empty name.`);
+			const { subscriptions } = work();
 			if (subscriptions.some((s) => s.topic === key && s.name === name)) throw new Error(`Topic "${key}" already has a subscription named "${name}". The name is what a job row records and what a retry counts against, so two cannot share one.`);
 			subscriptions.push({
 				topic: key,
@@ -1797,19 +2161,17 @@ registerResourceKind({
 	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;
+	work().queueRuntime = runtime;
 }
-var queueConsumers = /* @__PURE__ */ new Map();
 /** Every declared queue handler, for the worker to wire. */
 function declaredQueueConsumers() {
-	return [...queueConsumers.values()];
+	return [...work().queueConsumers.values()];
 }
 /** Forget declared queue handlers. For tests, alongside `resetDeclaredResources`. */
 function resetDeclaredQueueConsumers() {
-	queueConsumers.clear();
+	work().queueConsumers.clear();
 }
 /**
 * Declare a queue.
@@ -1831,11 +2193,12 @@ function queue(key, options = {}) {
 			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).`);
+			const runtime = work().queueRuntime;
+			if (!runtime) throw new Error(`Cannot enqueue on queue "${key}": no queue runtime is installed. ${missingRuntimeCause("queue")}`);
 			return runtime.enqueue(key, payload, enqueueOptions);
 		},
 		handler(fn) {
+			const { queueConsumers } = work();
 			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,
@@ -1971,6 +2334,426 @@ function isLazyComponentRef(ref) {
 	return typeof ref === "object" && ref !== null && "__rebaseLazy" in ref && ref.__rebaseLazy === true;
 }
 //#endregion
+//#region src/types/auth_adapter.ts
+/**
+* The request header that asks for a data-plane request to run as another
+* user, named by uid.
+*
+* The server honours it only on a signed-in administrator's own session —
+* never on an API key or the service key — and only through an adapter that
+* implements {@link AuthAdapter.resolveUser}. Everywhere else a request that
+* carries it is refused, never run as its caller.
+*
+* @group Auth
+*/
+var IMPERSONATE_HEADER = "x-rebase-impersonate";
+//#endregion
+//#region src/types/scopes.ts
+/**
+* Scopes — what a credential may do, named `resource:action`.
+*
+* One vocabulary for every way of reaching a Rebase backend: a person's
+* session, a service key, a personal key and an OAuth token for `/mcp` all
+* answer "may this caller do X?" with the same strings, so a grant reads the
+* same on a key, on a role and on a consent screen.
+*
+* A scope may carry a target — `data:read:posts` is `data:read` on the `posts`
+* collection only. The unqualified scope covers every target. Only the data
+* plane and app scopes take targets; see {@link SCOPE_TARGETS}.
+*
+* Two planes, held differently:
+*
+* - **The data plane** (`data:*`, `storage:*`, `functions:invoke`). Every
+*   signed-in person holds all of it, because what a person may do with data
+*   is decided row by row by the collection's `securityRules` and by storage
+*   policies, never by a scope. On a key or a token these scopes narrow: a key
+*   holding `data:read:posts` reaches nothing else, whatever RLS would allow.
+* - **The admin plane** (everything else). Nobody holds it implicitly. The
+*   `admin` role holds all of it; any other role holds what the app declares
+*   for it under `auth.roles` on the users collection.
+*
+* Apps declare their own scopes too (`auth.scopes`), named the same way —
+* `project:deploy`. Every signed-in person holds every app scope: like the data
+* plane, the function behind it decides whether the person may act, and the
+* scope exists so a key can be narrowed to that one action.
+*
+* @module
+*/
+/** @group Auth */
+var DATA_PLANE_SCOPES = [
+	"data:read",
+	"data:write",
+	"data:delete",
+	"storage:read",
+	"storage:write",
+	"storage:delete",
+	"functions:invoke"
+];
+/** @group Auth */
+var ADMIN_SCOPES = [
+	"users:read",
+	"users:write",
+	"schema:read",
+	"schema:write",
+	"database:read",
+	"database:write",
+	"backups:read",
+	"cron:read",
+	"cron:write",
+	"logs:read",
+	"keys:read",
+	"keys:write"
+];
+/** Every scope Rebase itself defines, in display order. @group Auth */
+var BUILT_IN_SCOPES = [...DATA_PLANE_SCOPES, ...ADMIN_SCOPES];
+/**
+* Scopes no key may hold.
+*
+* A key that could manage keys could mint its own successor, widen itself, or
+* revoke the keys other integrations run on — and revoking it would undo none
+* of that. Managing keys is for a person (or the service key).
+*
+* @group Auth
+*/
+var KEY_MANAGEMENT_SCOPES = ["keys:read", "keys:write"];
+/** The one built-in role. It holds every scope and is the RLS `admin` role. @group Auth */
+var ADMIN_ROLE = "admin";
+/**
+* The built-in scopes that accept a target, and what the target names.
+*
+* - `data:*` — a collection slug
+* - `storage:*` — a storage source id (`(default)` for the default source)
+* - `functions:invoke` — a custom function's name
+*
+* @group Auth
+*/
+var SCOPE_TARGETS = {
+	"data:read": "collection",
+	"data:write": "collection",
+	"data:delete": "collection",
+	"storage:read": "bucket",
+	"storage:write": "bucket",
+	"storage:delete": "bucket",
+	"functions:invoke": "function"
+};
+/** @group Auth */
+var BUILT_IN_SCOPE_DESCRIPTIONS = {
+	"data:read": {
+		label: "Read data",
+		description: "Read rows from collections, through the caller's row-level security."
+	},
+	"data:write": {
+		label: "Create and update data",
+		description: "Create and update rows in collections, through the caller's row-level security."
+	},
+	"data:delete": {
+		label: "Delete data",
+		description: "Delete rows from collections, through the caller's row-level security."
+	},
+	"storage:read": {
+		label: "Read files",
+		description: "List and download stored files."
+	},
+	"storage:write": {
+		label: "Upload files",
+		description: "Upload files and create folders."
+	},
+	"storage:delete": {
+		label: "Delete files",
+		description: "Delete stored files."
+	},
+	"functions:invoke": {
+		label: "Call functions",
+		description: "Call the backend's custom functions. A function can do anything its code does."
+	},
+	"users:read": {
+		label: "See users",
+		description: "List user accounts and their roles."
+	},
+	"users:write": {
+		label: "Manage users",
+		description: "Create, edit and delete accounts, reset passwords and second factors, and assign roles up to the holder's own."
+	},
+	"schema:read": {
+		label: "See the schema",
+		description: "Read the collection schema, plan schema changes and run the RLS audit."
+	},
+	"schema:write": {
+		label: "Change the schema",
+		description: "Apply schema changes: edits collection files and alters the database."
+	},
+	"database:read": {
+		label: "Inspect the database",
+		description: "List databases, tables, Postgres roles and branches."
+	},
+	"database:write": {
+		label: "Run SQL",
+		description: "Run SQL as the database owner, outside row-level security, and create or delete branches."
+	},
+	"backups:read": {
+		label: "Download backups",
+		description: "List and download database backups — every row, outside row-level security."
+	},
+	"cron:read": {
+		label: "See cron jobs",
+		description: "List cron jobs and read their run history."
+	},
+	"cron:write": {
+		label: "Run cron jobs",
+		description: "Trigger cron jobs and switch them on or off."
+	},
+	"logs:read": {
+		label: "Read server logs",
+		description: "Read the server's request and application logs."
+	},
+	"keys:read": {
+		label: "See service keys",
+		description: "List the project's service keys. Never grantable to a key."
+	},
+	"keys:write": {
+		label: "Manage service keys",
+		description: "Create, change and revoke the project's service keys. Never grantable to a key."
+	}
+};
+/** The access model of an app that declares nothing: built-ins only. @group Auth */
+var EMPTY_ACCESS_MODEL = {
+	roles: {},
+	scopes: {}
+};
+var SCOPE_PART = /^[a-z][a-z0-9-]*$/;
+/**
+* Split `resource:action[:target]`. Returns null for anything else.
+*
+* The target is everything after the second colon, so a target may itself
+* contain colons. Resource and action are lower-case words.
+*
+* @group Auth
+*/
+function parseScope(value) {
+	if (typeof value !== "string") return null;
+	const first = value.indexOf(":");
+	if (first < 0) return null;
+	const second = value.indexOf(":", first + 1);
+	const resource = value.slice(0, first);
+	const action = second < 0 ? value.slice(first + 1) : value.slice(first + 1, second);
+	if (!SCOPE_PART.test(resource) || !SCOPE_PART.test(action)) return null;
+	if (second < 0) return { scope: `${resource}:${action}` };
+	const target = value.slice(second + 1);
+	if (target.length === 0 || /\s/.test(target)) return null;
+	return {
+		scope: `${resource}:${action}`,
+		target
+	};
+}
+/** @group Auth */
+function isBuiltInScope(scope) {
+	return BUILT_IN_SCOPES.includes(scope);
+}
+/** @group Auth */
+function isDataPlaneScope(scope) {
+	return DATA_PLANE_SCOPES.includes(scope);
+}
+/** @group Auth */
+function isAdminScope(scope) {
+	return ADMIN_SCOPES.includes(scope);
+}
+/** Does this list of roles include the built-in `admin` role? @group Auth */
+function hasAdminRole(roles) {
+	return !!roles?.includes(ADMIN_ROLE);
+}
+/**
+* Does a set of held scopes grant `scope`, optionally on one `target`?
+*
+* The unqualified grant covers every target. A qualified grant covers its own
+* target only, and never answers an unqualified question: a key holding
+* `data:read:posts` is not asked "may you read data?" and told yes.
+*
+* @group Auth
+*/
+function scopeGrants(held, scope, target) {
+	for (const entry of held) {
+		if (entry === scope) return true;
+		if (target !== void 0 && entry === `${scope}:${target}`) return true;
+	}
+	return false;
+}
+/**
+* Does a set of held scopes grant `scope` on at least one target?
+*
+* For a surface that lists what is reachable — the collections an MCP client
+* may query — and filters per item afterwards.
+*
+* @group Auth
+*/
+function scopeGrantsAny(held, scope) {
+	const prefix = `${scope}:`;
+	return held.some((entry) => entry === scope || entry.startsWith(prefix));
+}
+/**
+* The targets a held set narrows `scope` to: `"all"` when it holds the
+* unqualified scope, otherwise the listed targets (possibly none).
+*
+* @group Auth
+*/
+function scopeTargets(held, scope) {
+	const prefix = `${scope}:`;
+	const targets = [];
+	for (const entry of held) {
+		if (entry === scope) return "all";
+		if (entry.startsWith(prefix)) targets.push(entry.slice(prefix.length));
+	}
+	return targets;
+}
+/**
+* Every scope a person holding `roles` has.
+*
+* The data plane and every app scope always; the whole admin plane with the
+* `admin` role; otherwise each declared role's scopes. A role nobody declared
+* adds nothing — it may still mean something to an RLS policy.
+*
+* @group Auth
+*/
+function scopesForRoles(roles, model = EMPTY_ACCESS_MODEL) {
+	const held = /* @__PURE__ */ new Set([...DATA_PLANE_SCOPES, ...Object.keys(model.scopes)]);
+	if (hasAdminRole(roles)) {
+		for (const scope of ADMIN_SCOPES) held.add(scope);
+		return [...held];
+	}
+	for (const role of roles ?? []) {
+		const definition = Object.prototype.hasOwnProperty.call(model.roles, role) ? model.roles[role] : void 0;
+		for (const scope of definition?.scopes ?? []) held.add(scope);
+	}
+	return [...held];
+}
+/**
+* Every scope this access model knows, unqualified: the built-ins, then the
+* app's own.
+*
+* @group Auth
+*/
+function knownScopes(model = EMPTY_ACCESS_MODEL) {
+	return [...BUILT_IN_SCOPES, ...Object.keys(model.scopes)];
+}
+/** Does this scope accept a target? @group Auth */
+function scopeAcceptsTarget(scope, model = EMPTY_ACCESS_MODEL) {
+	if (isBuiltInScope(scope)) return SCOPE_TARGETS[scope] !== void 0;
+	return (Object.prototype.hasOwnProperty.call(model.scopes, scope) ? model.scopes[scope] : void 0)?.target !== void 0;
+}
+/**
+* Check a list of scope strings against an access model. Returns the
+* problems, empty when every entry is a known scope with an acceptable target.
+*
+* @group Auth
+*/
+function validateScopes(values, model = EMPTY_ACCESS_MODEL) {
+	const known = new Set(knownScopes(model));
+	const problems = [];
+	for (const value of values) {
+		const text = typeof value === "string" ? value : String(value);
+		const parsed = typeof value === "string" ? parseScope(value) : null;
+		if (!parsed) problems.push({
+			scope: text,
+			reason: "malformed"
+		});
+		else if (!known.has(parsed.scope)) problems.push({
+			scope: text,
+			reason: "unknown"
+		});
+		else if (parsed.target !== void 0 && !scopeAcceptsTarget(parsed.scope, model)) problems.push({
+			scope: text,
+			reason: "target-not-accepted"
+		});
+	}
+	return problems;
+}
+/**
+* The entries of `requested` that `held` does not cover — what a credential
+* would hold beyond its minter. Empty means the request is within reach.
+*
+* `data:read:posts` is covered by `data:read`; `data:read` is not covered by
+* `data:read:posts`.
+*
+* @group Auth
+*/
+function scopesBeyond(requested, held) {
+	return requested.filter((entry) => {
+		const parsed = parseScope(entry);
+		if (!parsed) return true;
+		return !scopeGrants(held, parsed.scope, parsed.target);
+	});
+}
+/**
+* Narrow `requested` to what `held` covers, entry by entry. What a personal
+* key holds today when its owner has lost a role since it was minted.
+*
+* @group Auth
+*/
+function intersectScopes(requested, held) {
+	const beyond = new Set(scopesBeyond(requested, held));
+	return requested.filter((entry) => !beyond.has(entry));
+}
+/**
+* How a scope is worded for a person: the built-in description, the app's
+* declared label, or the raw string when nothing describes it. A target is
+* named after the label.
+*
+* @group Auth
+*/
+function describeScope(value, model = EMPTY_ACCESS_MODEL) {
+	const parsed = parseScope(value);
+	if (!parsed) return {
+		label: value,
+		description: ""
+	};
+	let base;
+	if (isBuiltInScope(parsed.scope)) base = BUILT_IN_SCOPE_DESCRIPTIONS[parsed.scope];
+	else if (Object.prototype.hasOwnProperty.call(model.scopes, parsed.scope)) {
+		const definition = model.scopes[parsed.scope];
+		base = {
+			label: definition.label,
+			description: definition.description ?? ""
+		};
+	}
+	const label = base?.label ?? parsed.scope;
+	return {
+		label: parsed.target !== void 0 ? `${label}: ${parsed.target}` : label,
+		description: base?.description ?? ""
+	};
+}
+/** The roles of an access model, `admin` first. @group Auth */
+function summarizeRoles(model = EMPTY_ACCESS_MODEL) {
+	return [{
+		id: ADMIN_ROLE,
+		name: "Admin",
+		description: "Holds every scope. Row-level security does not limit it: it reads, changes and deletes every row.",
+		scopes: [...ADMIN_SCOPES],
+		builtIn: true
+	}, ...Object.entries(model.roles).map(([id, definition]) => ({
+		id,
+		name: definition.name ?? id,
+		...definition.description ? { description: definition.description } : {},
+		scopes: [...definition.scopes],
+		builtIn: false
+	}))];
+}
+/** Every scope of an access model, described, in display order. @group Auth */
+function summarizeScopes(model = EMPTY_ACCESS_MODEL) {
+	const builtIn = BUILT_IN_SCOPES.map((scope) => ({
+		scope,
+		...BUILT_IN_SCOPE_DESCRIPTIONS[scope],
+		...SCOPE_TARGETS[scope] ? { target: SCOPE_TARGETS[scope] } : {},
+		plane: isDataPlaneScope(scope) ? "data" : "admin"
+	}));
+	const app = Object.entries(model.scopes).map(([scope, definition]) => ({
+		scope,
+		label: definition.label,
+		description: definition.description ?? "",
+		...definition.target ? { target: definition.target } : {},
+		plane: "app"
+	}));
+	return [...builtIn, ...app];
+}
+//#endregion
 //#region src/types/project_manifest.ts
 /**
 * Path prefixes the backend owns, which no static app may claim.
@@ -2008,6 +2791,91 @@ function reservedPrefixFor(path) {
 	return RESERVED_BACKEND_PREFIXES.find((reserved) => normalized === reserved || normalized.startsWith(`${reserved}/`));
 }
 /**
+* Split a static app's declared `path` into the hostname it claims and the path
+* under it.
+*
+* `"/admin"` is `{ path: "/admin" }`, returned as written: the path rules
+* (leading slash, no `..`, reserved prefixes) belong to the caller, which
+* applies them to the path part of either form. `"https://admin.example.com/cms"`
+* is `{ host: "admin.example.com", path: "/cms" }`.
+*
+* Shared because three parties must read the same value the same way: the CLI
+* while `rebase.json` is edited, the control plane at deploy intake (a bundle can
+* come from any CLI, or none), and the runtime choosing which app answers.
+*/
+function parseAppAddress(value) {
+	if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) {
+		if (!value.startsWith("/") && isValidAppHost(value.toLowerCase().replace(/\/.*$/, ""))) return {
+			ok: false,
+			reason: `looks like a hostname — write it as a URL: "https://${value}"`
+		};
+		return {
+			ok: true,
+			address: { path: value }
+		};
+	}
+	if (/[\s\\\u0000-\u001f\u007f]/.test(value)) return {
+		ok: false,
+		reason: "must not contain spaces, control characters or backslashes"
+	};
+	const authority = value.slice(value.indexOf("//") + 2).split(/[/?#]/)[0];
+	if (/:[^@]*$/.test(authority) && !authority.startsWith("[")) return {
+		ok: false,
+		reason: "must not name a port — a hostname is served on 443"
+	};
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return {
+			ok: false,
+			reason: "is not a valid URL"
+		};
+	}
+	if (url.protocol !== "https:") return {
+		ok: false,
+		reason: `must use https — the platform serves every hostname over TLS: "https://${url.host}${url.pathname === "/" ? "" : url.pathname}"`
+	};
+	if (url.username || url.password) return {
+		ok: false,
+		reason: "must not contain credentials"
+	};
+	if (url.port) return {
+		ok: false,
+		reason: "must not name a port — a hostname is served on 443"
+	};
+	if (url.search || url.hash || /[?#]/.test(value)) return {
+		ok: false,
+		reason: "must not have a query or fragment"
+	};
+	if (!isValidAppHost(url.hostname)) return {
+		ok: false,
+		reason: `names "${url.hostname}", which is not a public hostname`
+	};
+	const authorityAndPath = value.slice(value.indexOf("//") + 2);
+	const slash = authorityAndPath.indexOf("/");
+	return {
+		ok: true,
+		address: {
+			host: url.hostname,
+			path: slash === -1 ? "/" : authorityAndPath.slice(slash)
+		}
+	};
+}
+/**
+* Whether `host` is a public DNS name an app can be given: lowercase labels of
+* letters, digits and hyphens, at least two of them, not an IP address and not
+* `localhost`. Internationalised names arrive here already in punycode.
+*/
+function isValidAppHost(host) {
+	if (host.length === 0 || host.length > 253 || host !== host.toLowerCase()) return false;
+	const labels = host.split(".");
+	if (labels.length < 2) return false;
+	const label = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+	if (!labels.every((part) => label.test(part))) return false;
+	return !/^[0-9]+$/.test(labels[labels.length - 1]);
+}
+/**
 * Version of the bundle *format* itself.
 *
 * Bumped only when the on-disk layout changes in a way an older runtime could
@@ -2370,10 +3238,13 @@ var BATCH_REF_KEY = "$ref";
 * one, which is the case worth catching.
 *
 * Any `$`-prefixed key counts, because `{ $increment: 1 }` written to a number
-* column as a JSON document is the failure this exists to prevent. No collection
-* can declare a column whose value legitimately has a key beginning with `$`: a
-* `map` property's sub-keys are declared, and `$` is not valid in the
-* identifiers the DDL generators emit.
+* column as a JSON document is the failure this exists to prevent.
+*
+* Except on a `map` (pass `propertyType`): a map's value is a JSON document,
+* and one may legitimately carry `$` keys — a JSON Schema's `$schema`, a
+* MongoDB-style export. There, only a single-key object whose key is one of
+* {@link FIELD_OPERATORS} is an operation, and anything else is data. A caller
+* that does not know the property type gets the strict reading.
 *
 * The one exception is `{ $ref: … }`, the batch's backward reference. It stands
 * where a *value* goes and is resolved to one before the row is written, so it
@@ -2382,15 +3253,16 @@ var BATCH_REF_KEY = "$ref";
 *
 * @group Data
 */
-function isFieldOperation(value) {
+function isFieldOperation(value, propertyType) {
 	if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date) return false;
 	const keys = Object.keys(value);
 	if (keys.length === 1 && keys[0] === "$ref") return false;
+	if (propertyType === "map") return keys.length === 1 && FIELD_OPERATORS.includes(keys[0]);
 	return keys.some((key) => key.startsWith("$"));
 }
 /** True when any value in a write payload is (or is attempting to be) one. @group Data */
 function hasFieldOperation(values) {
-	return !!values && Object.values(values).some(isFieldOperation);
+	return !!values && Object.values(values).some((value) => isFieldOperation(value));
 }
 //#endregion
 //#region src/controllers/data_driver.ts
@@ -2458,9 +3330,33 @@ function resolveClientListLimit(rawLimit, opts = {}) {
 */
 var PUBLIC_STORAGE_PREFIX = "public/";
 /**
-* True when a storage key/path points at a public object (lives under
-* {@link PUBLIC_STORAGE_PREFIX}). The check is applied to the key *within the
-* bucket* — strip any `bucket/` and `scheme://` prefixes first.
+* True when a storage **key** is public: it lies under
+* {@link PUBLIC_STORAGE_PREFIX}.
+*
+* The key is read exactly as it is — the canonical key within its bucket, the
+* one the server stores, serves, and hands a `storageAuthorize` hook as
+* `key` — and nothing is parsed out of it. That is the difference from
+* {@link isPublicStoragePath}, which reads a client-side *path* and so strips
+* a `scheme://` and a leading `default/` bucket segment first. On a key both are
+* wrong: `default/public/x` is a key in a folder called `default`, and a
+* request path `notes://public/x` names the key `notes:/public/x`. Neither is
+* public, and the server decides on this function so that it never says they
+* are.
+*
+* @group Models
+*/
+function isPublicStorageKey(key) {
+	if (!key || !key.startsWith("public/")) return false;
+	return !key.split(/[\\/]/).includes("..");
+}
+/**
+* True when a storage key or client-side path points at a public object
+* (lives under {@link PUBLIC_STORAGE_PREFIX}).
+*
+* For a path as a client holds it: a `scheme://` prefix and a single leading
+* `default/` bucket segment are stripped first. The server and a
+* `storageAuthorize` hook, which hold the canonical key, use
+* {@link isPublicStorageKey}.
 *
 * @group Models
 */
@@ -2473,7 +3369,295 @@ function isPublicStoragePath(path) {
 	if (p.split("/").some((seg) => seg === "..")) return false;
 	return p.startsWith("public/") || p.startsWith(`default/public/`);
 }
+/**
+* The path the storage routes address an object by, from a key or from the
+* `storageUrl` an upload returned (`<scheme>://<bucket>/<key>`, which is what a
+* property with `includeBucketUrl: true` keeps in its column).
+*
+* The routes address a source's objects by key. On S3 and GCS the bucket in a
+* `storageUrl` is always the source's own — the server refuses any other — so
+* it is dropped: sent along, `s3://acme-media/products/a.png` reached the
+* server as the key `acme-media/products/a.png`, the preview found nothing and
+* a delete reported success while the object stayed. It worked on local disk
+* only, because `local://default/<key>` happens to carry the one bucket
+* segment the routes recognise — which is kept, as is any other local bucket.
+*
+* A bare key whose first folder is `default` is sent behind that bucket
+* segment. The routes read one leading `default/` (in any case) as the bucket,
+* so the key `default/photo.png` sent as it is names the root `photo.png`:
+* {@link defaultBucketPath} is the spelling that names the key itself.
+*
+* Shared by every storage source that talks to those routes, so they address
+* an object alike.
+*
+* @group Models
+*/
+function storageObjectPath(keyOrUrl, bucket) {
+	let filePath = keyOrUrl;
+	let bucketQualified = false;
+	const scheme = /^(local|s3|gs):\/\//.exec(filePath);
+	if (scheme) {
+		filePath = filePath.substring(scheme[0].length);
+		if (scheme[1] !== "local") {
+			const slash = filePath.indexOf("/");
+			if (slash > 0) filePath = filePath.substring(slash + 1);
+		} else bucketQualified = true;
+	}
+	if (bucket && filePath) {
+		if (!filePath.startsWith(`${bucket}/`)) filePath = `${bucket}/${filePath}`;
+		bucketQualified = true;
+	}
+	return bucketQualified ? filePath : defaultBucketPath(filePath);
+}
+/**
+* The request path of a key in the default bucket: the key itself, unless the
+* routes would read its first folder as the bucket — a first folder named
+* `default`, matched as the routes match it (case-insensitively, and only when
+* something follows it). Then the bucket segment goes in front, so exactly the
+* one segment the routes strip is the one added.
+*/
+function defaultBucketPath(key) {
+	const segments = key.split("/");
+	return segments.length > 1 && segments[0].toLowerCase() === "default" ? `default/${key}` : key;
+}
+//#endregion
+//#region src/controllers/storage-references.ts
+/**
+* The scheme of a **storage reference**: a stored object named inside text.
+*
+* Text that embeds a file — a markdown body above all — cannot hold a private
+* object's URL: that URL carries a download token which expires in minutes,
+* after which every reader of the text gets a 401 for an image that is still in
+* the bucket. It holds a reference instead,
+* `rebase-storage:posts/cover.png` (`?storageId=media` for a named source),
+* and whoever renders the text exchanges each reference for a fresh URL with
+* {@link resolveStorageReferences} — `resolveStorageReferences(text, client)`
+* from `@rebasepro/client` on a site.
+*
+* @group Models
+*/
+var STORAGE_REFERENCE_SCHEME = "rebase-storage:";
+/**
+* `encodeURIComponent`, plus the five characters it leaves alone that end or
+* break a markdown link destination: `(`, `)`, `'`, `!` and `*`.
+*/
+var encodeReferencePart = (part) => encodeURIComponent(part).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+/**
+* A reference as it appears in text: the scheme, then the characters
+* {@link storageReference} writes. Kept beside {@link STORAGE_REFERENCE_SCHEME};
+* the test round-trips names chosen to break it.
+*/
+var STORAGE_REFERENCE_PATTERN = /rebase-storage:[A-Za-z0-9\-._~%/?=&]+/g;
+/**
+* The reference for an object — what text stores in place of its URL.
+*
+* Every part is percent-encoded, so the reference contains no space,
+* parenthesis or quote and survives as one markdown link destination whatever
+* the file was called.
+*
+* @group Models
+*/
+function storageReference(key, storageId) {
+	return `${STORAGE_REFERENCE_SCHEME}${key.replace(/^\/+/, "").split("/").map(encodeReferencePart).join("/")}${storageId && storageId !== "(default)" ? `?storageId=${encodeReferencePart(storageId)}` : ""}`;
+}
+/**
+* Whether a string — an image's `src`, a link's `href` — is a storage reference.
+*
+* @group Models
+*/
+function isStorageReference(value) {
+	return typeof value === "string" && value.startsWith("rebase-storage:");
+}
+/**
+* The object a storage reference names, or `null` for anything else — a URL, a
+* bare key, or a reference whose key would climb out of its prefix.
+*
+* @group Models
+*/
+function parseStorageReference(value) {
+	if (!isStorageReference(value)) return null;
+	const rest = value.slice(15);
+	const queryAt = rest.indexOf("?");
+	const rawPath = queryAt === -1 ? rest : rest.slice(0, queryAt);
+	const query = queryAt === -1 ? "" : rest.slice(queryAt + 1);
+	let key;
+	let storageId;
+	try {
+		key = rawPath.split("/").map(decodeURIComponent).join("/");
+		for (const pair of query.split("&")) {
+			const [name, raw] = pair.split("=");
+			if (name === "storageId" && raw) storageId = decodeURIComponent(raw);
+		}
+	} catch {
+		return null;
+	}
+	if (!key || key.split("/").some((segment) => segment === "..")) return null;
+	return storageId && storageId !== "(default)" ? {
+		key,
+		storageId
+	} : { key };
+}
+/** The JSON in a JWT's payload segment, or `undefined` for anything else. */
+function jwtPayload(token) {
+	const segments = token.split(".");
+	if (segments.length !== 3) return void 0;
+	try {
+		const base64 = segments[1].replace(/-/g, "+").replace(/_/g, "/");
+		const binary = atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, "="));
+		const json = new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0)));
+		const payload = JSON.parse(json);
+		return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* The object a private file's download URL was minted for, or `null` for any
+* other URL.
+*
+* Text written before storage references stored such URLs —
+* `…/storage/file/posts/cover.png?token=…` — and their tokens expired minutes
+* later. The token still names the object it was minted for, so the URL can be
+* traded for a fresh one, or for a reference. Read without verifying the
+* token: it grants nothing here, it only says which object is meant, and the
+* key in the URL must agree with it. Host-agnostic, since a URL written
+* through one origin may be read through another.
+*
+* @group Models
+*/
+function storageTargetOfDownloadUrl(url) {
+	let parsed;
+	try {
+		parsed = new URL(url, "http://relative.invalid");
+	} catch {
+		return null;
+	}
+	const at = parsed.pathname.indexOf("/storage/file/");
+	const token = parsed.searchParams.get("token");
+	if (at === -1 || !token) return null;
+	let key;
+	try {
+		key = parsed.pathname.slice(at + 14).split("/").map(decodeURIComponent).join("/");
+	} catch {
+		return null;
+	}
+	if (!key || key.split("/").some((segment) => segment === "..")) return null;
+	const payload = jwtPayload(token);
+	if (payload?.purpose !== "file-read" || typeof payload.path !== "string") return null;
+	const slash = payload.path.indexOf("/");
+	if (payload.path !== key && payload.path.slice(slash + 1) !== key) return null;
+	const named = parsed.searchParams.get("storageId") ?? (typeof payload.storageId === "string" ? payload.storageId : void 0);
+	return named && named !== "(default)" ? {
+		key,
+		storageId: named
+	} : { key };
+}
+/**
+* A private file's download URL as it may appear in text. Parentheses are
+* allowed in the path, where an unencoded file name puts them; the query, a
+* token, has none, so the match ends where a markdown destination does.
+*/
+var DOWNLOAD_URL_PATTERN = /(?:https?:\/\/[^\s()<>"'\]]+)?\/storage\/file\/[^\s<>"'?#\]]+\?[^\s()<>"'#\]]*/g;
+/** Each download URL in `text` that names an object, with its reference. */
+function downloadUrlsIn(text) {
+	const found = /* @__PURE__ */ new Map();
+	if (!text.includes("/storage/file/")) return found;
+	for (const url of text.match(DOWNLOAD_URL_PATTERN) ?? []) {
+		const target = storageTargetOfDownloadUrl(url);
+		if (target) found.set(url, storageReference(target.key, target.storageId));
+	}
+	return found;
+}
+/**
+* Every object `text` names: its storage references, and the private files'
+* download URLs saved in it before references existed. An object named more
+* than once may be listed more than once.
+*
+* @group Models
+*/
+function storageTargetsInText(text) {
+	return [...text.includes("rebase-storage:") ? text.match(STORAGE_REFERENCE_PATTERN) ?? [] : [], ...downloadUrlsIn(text).values()].map((reference) => parseStorageReference(reference)).filter((target) => target !== null);
+}
+/**
+* `text` with every private file's download URL replaced by the storage
+* reference for its object — for rewriting text saved before references, so
+* it stores what new text stores. Any other URL is left as it is.
+*
+* @group Models
+*/
+function storageReferencesForDownloadUrls(text) {
+	const urls = downloadUrlsIn(text);
+	if (urls.size === 0) return text;
+	return text.replace(DOWNLOAD_URL_PATTERN, (url) => urls.get(url) ?? url);
+}
+/**
+* Exchange every storage reference in `text` for a URL, at the moment the text
+* is rendered.
+*
+* ```ts
+* const html = markdown.render(await resolveStorageReferences(post.body, client));
+* ```
+*
+* Each distinct object is asked for once — `getSignedUrl(key)` on its source —
+* so a private object gets a freshly minted download URL every time the text is
+* rendered. A reference that cannot be resolved (no such object, an unknown
+* source) is left as it was, so a missing object reads as a missing image
+* rather than as a failed render.
+*
+* A private file's download URL saved in the text before references existed
+* is renewed the same way: its expired token still names the object (see
+* {@link storageTargetOfDownloadUrl}). One that cannot be resolved is left as
+* it was.
+*
+* @group Models
+*/
+async function resolveStorageReferences(text, from) {
+	if (!text) return text;
+	const downloadUrls = downloadUrlsIn(text);
+	if (!text.includes("rebase-storage:") && downloadUrls.size === 0) return text;
+	const resolve = typeof from === "function" ? from : resolverFromSources(from);
+	const references = /* @__PURE__ */ new Set([...text.match(STORAGE_REFERENCE_PATTERN) ?? [], ...downloadUrls.values()]);
+	const urls = /* @__PURE__ */ new Map();
+	await Promise.all([...references].map(async (reference) => {
+		const target = parseStorageReference(reference);
+		if (!target) return;
+		try {
+			const url = await resolve(target);
+			if (url) urls.set(reference, url);
+		} catch {}
+	}));
+	if (urls.size === 0) return text;
+	return (downloadUrls.size === 0 ? text : text.replace(DOWNLOAD_URL_PATTERN, (saved) => {
+		const reference = downloadUrls.get(saved);
+		const url = reference === void 0 ? void 0 : urls.get(reference);
+		return url === void 0 ? saved : asLinkDestination(url);
+	})).replace(STORAGE_REFERENCE_PATTERN, (reference) => {
+		const url = urls.get(reference);
+		return url === void 0 ? reference : asLinkDestination(url);
+	});
+}
+/**
+* A URL as one markdown link destination: whitespace, parentheses, angle
+* brackets and quotes percent-encoded, since any of them ends the destination
+* and turns the image into literal text. The URL means the same thing either
+* way.
+*/
+var asLinkDestination = (url) => url.replace(/[\s()<>"']/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
+/** A resolver over a client's storage sources, one source per named key. */
+function resolverFromSources(client) {
+	const named = /* @__PURE__ */ new Map();
+	return async ({ key, storageId }) => {
+		let source = client.storage;
+		if (storageId) {
+			if (!named.has(storageId)) named.set(storageId, client.createStorageSource?.(storageId));
+			source = named.get(storageId);
+		}
+		if (!source) return null;
+		const config = await source.getSignedUrl(key);
+		return config.fileNotFound ? null : config.url;
+	};
+}
 //#endregion
-export { ADMIN_COLLECTION_KEYS, ADMIN_PROPERTY_KEYS, ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, BATCH_REF_KEY, 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_MODE, DEFAULT_SEARCH_WEIGHT, DEFAULT_STORAGE_SOURCE_KEY, DEFAULT_TENANT_BYPASS_ROLES, DEFAULT_VECTOR_LIST_LIMIT, EntityReference, EntityRelation, FIELD_OPERATORS, FIREBASE_CAPABILITIES, GeoPoint, JUNCTION_PIVOT_KEY, LEGACY_RLS_JWT_SQL, LEGACY_RLS_ROLES_SQL, LEGACY_RLS_SCHEMA, LEGACY_RLS_UID_SQL, LIST_OPS, ListLimitError, MAX_INCLUDE_DEPTH, 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, hasFieldOperation, hasForeignKeyOnTarget, isAnonymousUid, isBranchAdmin, isChannelBusInstance, isDocumentAdmin, isFieldOperation, isFirebaseCollectionConfig, isLazyComponentRef, isManyToMany, isMongoDBCollectionConfig, isPostgresCollectionConfig, isPublicStoragePath, isRelationAggregateSort, isRelationalCollectionConfig, isResourceHandle, isSQLAdmin, isSchemaAdmin, isSchemaEditingAdmin, isSerializedCollectionRef, isTenantClaimSource, isTenantMembershipSource, isToMany, isUnsupported, isValidEngine, nestAdminCollectionKeys, nestAdminKeysOf, nestAdminPropertyKeys, parseEnvBoolean, 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 };
+export { ADMIN_COLLECTION_KEYS, ADMIN_PROPERTY_KEYS, ADMIN_ROLE, ADMIN_SCOPES, ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, BATCH_REF_KEY, BUILT_IN_SCOPES, BUILT_IN_SCOPE_DESCRIPTIONS, BUNDLE_FORMAT_VERSION, CANONICAL_TO_REST, DATA_PLANE_SCOPES, 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_MODE, DEFAULT_SEARCH_WEIGHT, DEFAULT_STORAGE_SOURCE_KEY, DEFAULT_TENANT_BYPASS_ROLES, DEFAULT_VECTOR_LIST_LIMIT, EMPTY_ACCESS_MODEL, EntityReference, EntityRelation, FIELD_OPERATORS, FIREBASE_CAPABILITIES, GeoPoint, IMPERSONATE_HEADER, INCLUDE_COUNT_KEY, JUNCTION_PIVOT_KEY, KEY_MANAGEMENT_SCOPES, LEGACY_RLS_JWT_SQL, LEGACY_RLS_ROLES_SQL, LEGACY_RLS_SCHEMA, LEGACY_RLS_UID_SQL, LIST_OPS, ListLimitError, MAX_INCLUDE_DEPTH, 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, RUNTIME_ONLY_COLLECTION_KEYS, RebaseApiError, RebaseClientError, SCHEMA_VERSION_HEADER, SCOPE_TARGETS, STORAGE_REFERENCE_SCHEME, Vector, amendResourceKind, applyCollectionPatch, bucket, buildResourceGraph, canonicalSchemaPayload, collectionPatchProblems, computeSchemaVersion, database, declareCron, declareFunction, declareResource, declaredDataSources, declaredDatabaseExtensions, declaredQueueConsumers, declaredResources, declaredStorageSources, declaredSubscriptions, describeScope, deserializeCollections, diffCollections, diffJsonValues, encodeRelationAggregateSort, envBasesForResource, findEnvSuffixCollision, findStorageSuffixCollision, getCollectionDataPath, getDataSourceCapabilities, getDeclaredSubcollections, hasAdminRole, hasFieldOperation, hasForeignKeyOnTarget, intersectScopes, isAdminScope, isAnonymousUid, isBranchAdmin, isBuiltInScope, isChannelBusInstance, isCollectionPatch, isDataPlaneScope, isDocumentAdmin, isFieldOperation, isFirebaseCollectionConfig, isLazyComponentRef, isManyToMany, isMongoDBCollectionConfig, isPostgresCollectionConfig, isPublicStorageKey, isPublicStoragePath, isRelationAggregateSort, isRelationalCollectionConfig, isResourceHandle, isSQLAdmin, isSchemaAdmin, isSchemaEditingAdmin, isSerializedCollectionRef, isStorageReference, isTenantClaimSource, isTenantMembershipSource, isToMany, isUnsupported, isValidAppHost, isValidEngine, knownScopes, nestAdminCollectionKeys, nestAdminKeysOf, nestAdminPropertyKeys, nestCollectionPatchPaths, parseAppAddress, parseEnvBoolean, parseRelationAggregateSort, parseScope, parseStorageReference, policy, queue, registerDataSourceCapabilities, registerResourceKind, reservedPrefixFor, resetDeclaredQueueConsumers, resetDeclaredResources, resetDeclaredSubscriptions, resolveClientListLimit, resolveResourceRefs, resolveStorageReferences, resourceEnvSuffix, resourceId, resourceKeyOf, resourceKind, resourceKinds, resourceToDataSource, resourceToStorageSource, rewriteLegacyRlsFunctions, runtimeOnlyKeyIn, scopeAcceptsTarget, scopeGrants, scopeGrantsAny, scopeTargets, scopesBeyond, scopesForRoles, serializeCollections, setQueueRuntime, setTopicRuntime, sortKeyToString, storageEnvSuffix, storageObjectPath, storageReference, storageReferencesForDownloadUrls, storageTargetOfDownloadUrl, storageTargetsInText, summarizeRoles, summarizeScopes, toCanonicalOp, toCollectionJson, topic, unsupportedMethod, usesLegacyRlsFunctions, validateScopes };
 
 //# sourceMappingURL=index.es.js.map