emdash 0.32.0 → 0.33.0

package/src/loader.ts

@@ -88,12 +88,19 @@ const SYSTEM_COLUMNS = new Set([
 	// SEO_ALIAS_COLUMNS, never as flat fields.
 	"_emdash_terms",
 	"_emdash_bylines",
+	"_emdash_bylines_exist",
 	SEO_FOLDED_COLUMN,
 ]);
 
 /** Markers for byline/taxonomy hydration folded into the content query. */
 export const FOLDED_TERMS = Symbol.for("emdash:foldedTerms");
 export const FOLDED_BYLINES = Symbol.for("emdash:foldedBylines");
+/**
+ * Marker for whether `_emdash_bylines` has any rows at all (`false` = table
+ * empty). Lets byline hydration trust an empty fold instead of re-checking
+ * via the byline query path on sites that never use bylines.
+ */
+export const FOLDED_BYLINES_EXIST = Symbol.for("emdash:foldedBylinesExist");
 
 /**
  * Correlated JSON-array subqueries that fold taxonomy-term and byline hydration
@@ -144,7 +151,12 @@ function foldedHydrationSelects(db: Kysely<any>, type: string, outer: string) {
 		: sql.raw("json_object('roleLabel', cb.role_label, 'sortOrder', cb.sort_order, 'byline', ");
 	const credit = sql`${creditObj}${bylineInner})`;
 	const bylines = sql`(SELECT ${agg(credit)} FROM ${sql.ref("_emdash_content_bylines")} AS cb ${foldJoin} ${sql.ref("_emdash_bylines")} AS b ON b.translation_group = cb.byline_id LEFT JOIN ${sql.ref("media")} AS m ON m.id = b.avatar_media_id WHERE cb.collection_slug = ${type} AND cb.content_id = ${o}.id AND b.locale = ${o}.locale) AS ${sql.ref("_emdash_bylines")}`;
-	return { terms, bylines };
+	// Uncorrelated existence probe (evaluated once per statement, not per row):
+	// 1 when `_emdash_bylines` has any row, NULL when empty. An empty table
+	// means an empty fold is authoritative — no credit in any locale, no
+	// author-fallback byline — so hydration can skip the byline query path.
+	const bylinesExist = sql`(SELECT 1 FROM ${sql.ref("_emdash_bylines")} LIMIT 1) AS ${sql.ref("_emdash_bylines_exist")}`;
+	return { terms, bylines, bylinesExist };
 }
 
 /**
@@ -227,6 +239,16 @@ function stashFolded(data: Record<string, unknown>, row: Record<string, unknown>
 		}
 		Object.defineProperty(data, sym, { value, enumerable: false, configurable: true });
 	}
+	// Existence probe: 1 = table has rows, NULL = empty (both dialects). A row
+	// without the column (e.g. a cached snapshot) leaves the marker unset,
+	// which hydration treats as "unknown" and falls back conservatively.
+	if ("_emdash_bylines_exist" in row) {
+		Object.defineProperty(data, FOLDED_BYLINES_EXIST, {
+			value: row["_emdash_bylines_exist"] != null,
+			enumerable: false,
+			configurable: true,
+		});
+	}
 }
 
 /** Resolved SEO shape attached to `entry.data.seo`. Mirrors `ContentSeo`. */
@@ -703,8 +725,8 @@ function buildPivotLimitOffset(
  * Options for {@link buildTaxonomyPivotQuery}.
  *
  * Parameterized on the `deletedIsNull` predicate and `status` condition so the
- * same builder serves the public live path (`deleted_at IS NULL` + published/
- * scheduled) and, without any schema change, an admin trash (`deleted_at IS NOT
+ * same builder serves the public live path (`deleted_at IS NULL` + published)
+ * and, without any schema change, an admin trash (`deleted_at IS NOT
  * NULL`) or all-statuses shape. Admin wiring is out of scope today; the
  * parameters exist so `ContentRepository` can adopt this if it gains taxonomy
  * filtering.
@@ -727,7 +749,7 @@ export interface TaxonomyPivotQueryOptions {
 	locale: string | undefined;
 	/**
 	 * Status shape. A concrete value (`published`/`draft`/…) applies the same
-	 * condition `buildStatusCondition` produces (public: published-or-scheduled).
+	 * condition `buildStatusCondition` produces (public: published only).
 	 * `undefined` drops the status filter entirely — the admin all-statuses shape.
 	 */
 	status: string | undefined;
@@ -826,11 +848,11 @@ export function buildTaxonomyPivotQuery(
 		: sql``;
 
 	const firstGroupCond = pivotGroupCondition("ct.taxonomy_id", firstGroups);
-	const { terms: termsSelect, bylines: bylinesSelect } = foldedHydrationSelects(
-		db,
-		collection,
-		"r",
-	);
+	const {
+		terms: termsSelect,
+		bylines: bylinesSelect,
+		bylinesExist: bylinesExistSelect,
+	} = foldedHydrationSelects(db, collection, "r");
 
 	// Authoritative re-check on the joined `ec_*` row.
 	const deletedR = deletedIsNull ? sql`r.deleted_at IS NULL` : sql`r.deleted_at IS NOT NULL`;
@@ -871,7 +893,7 @@ export function buildTaxonomyPivotQuery(
 				ORDER BY sortval ${dir}, ct.entry_id ${dir}
 				${limitClause}
 			)
-			SELECT r.*, ${termsSelect}, ${bylinesSelect}
+			SELECT r.*, ${termsSelect}, ${bylinesSelect}, ${bylinesExistSelect}
 			FROM picked JOIN ${sql.ref(tableName)} AS r ON r.id = picked.entry_id
 			WHERE ${deletedR} ${statusR} ${localeR}
 			ORDER BY picked.sortval ${dir}, picked.entry_id ${dir}
@@ -894,7 +916,7 @@ export function buildTaxonomyPivotQuery(
 				${residual}
 				${bylineCt}
 		)
-		SELECT r.*, ${termsSelect}, ${bylinesSelect}
+		SELECT r.*, ${termsSelect}, ${bylinesSelect}, ${bylinesExistSelect}
 		FROM picked JOIN ${sql.ref(tableName)} AS r ON r.id = picked.entry_id
 		WHERE ${deletedR} ${statusR} ${localeR}
 			${cursorCond}
@@ -1257,11 +1279,11 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 						: sql``;
 
 					// Fold byline + taxonomy hydration into the list query.
-					const { terms: termsSelect, bylines: bylinesSelect } = foldedHydrationSelects(
-						db,
-						type,
-						tableName,
-					);
+					const {
+						terms: termsSelect,
+						bylines: bylinesSelect,
+						bylinesExist: bylinesExistSelect,
+					} = foldedHydrationSelects(db, type, tableName);
 
 					// LIMIT/OFFSET clause. SQLite only accepts OFFSET when a
 					// LIMIT is present, so a bare offset uses `LIMIT -1`
@@ -1277,7 +1299,7 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 							: sql`LIMIT -1 OFFSET ${offset}`;
 					}
 					result = await sql<Record<string, unknown>>`
-						SELECT *, ${termsSelect}, ${bylinesSelect} FROM ${sql.ref(tableName)}
+						SELECT *, ${termsSelect}, ${bylinesSelect}, ${bylinesExistSelect} FROM ${sql.ref(tableName)}
 						WHERE deleted_at IS NULL
 						AND ${statusCondition}
 						${localeFilter}
@@ -1413,22 +1435,22 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 				// per-result-set column limit, surfacing as a silent null entry. One
 				// JSON column is one column, so the join stays safe at any width and
 				// we keep the single round trip.
-				const { terms: termsSelect, bylines: bylinesSelect } = foldedHydrationSelects(
-					db,
-					type,
-					"c",
-				);
+				const {
+					terms: termsSelect,
+					bylines: bylinesSelect,
+					bylinesExist: bylinesExistSelect,
+				} = foldedHydrationSelects(db, type, "c");
 				const seoSelect = foldedSeoSelect(db, type, "c");
 				const result = locale
 					? await sql<Record<string, unknown>>`
-							SELECT c.*, ${seoSelect}, ${termsSelect}, ${bylinesSelect}
+							SELECT c.*, ${seoSelect}, ${termsSelect}, ${bylinesSelect}, ${bylinesExistSelect}
 							FROM ${sql.ref(tableName)} AS c
 							WHERE c.deleted_at IS NULL
 							AND ((c.slug = ${id} AND c.locale = ${locale}) OR c.id = ${id})
 							LIMIT 1
 						`.execute(db)
 					: await sql<Record<string, unknown>>`
-							SELECT c.*, ${seoSelect}, ${termsSelect}, ${bylinesSelect}
+							SELECT c.*, ${seoSelect}, ${termsSelect}, ${bylinesSelect}, ${bylinesExistSelect}
 							FROM ${sql.ref(tableName)} AS c
 							WHERE c.deleted_at IS NULL
 							AND (c.slug = ${id} OR c.id = ${id})

package/src/media/usage/gc.ts

@@ -0,0 +1,50 @@
+/**
+ * Media-usage generation GC.
+ *
+ * Every save writes a fresh generation of `_emdash_media_usage` rows and
+ * leaves the superseded generation behind; reads join on
+ * `current_generation`, so non-current rows are dead weight. This sweep
+ * composes the repository GC methods behind a shared cutoff and batch limit,
+ * and is called from `runSystemCleanup` on every scheduler tick.
+ */
+
+import type { Kysely } from "kysely";
+
+import { MediaUsageRepository } from "../../database/repositories/media-usage.js";
+import type { Database } from "../../database/types.js";
+
+/**
+ * Only rows older than this are collected. Guarded writers insert occurrence
+ * rows before winning the source CAS, so the window must exceed any plausible
+ * in-flight write; mirrors the pending-upload abandonment window.
+ */
+const GC_MAX_AGE_MS = 60 * 60 * 1000;
+
+/**
+ * Per-tick cap on rows considered by each GC method, so a large backlog is
+ * amortized across ticks instead of one oversized batch (D1 bind limits).
+ */
+const GC_BATCH_LIMIT = 500;
+
+export interface MediaUsageCleanupResult {
+	staleGenerations: number;
+	abandonedGenerations: number;
+	orphanOccurrences: number;
+}
+
+/**
+ * Delete media-usage occurrence rows that can no longer be read: superseded
+ * generations, generations abandoned by losing CAS writers, and occurrences
+ * whose source row is gone.
+ */
+export async function cleanupMediaUsageGenerations(
+	db: Kysely<Database>,
+): Promise<MediaUsageCleanupResult> {
+	const cutoff = new Date(Date.now() - GC_MAX_AGE_MS).toISOString();
+	const repo = new MediaUsageRepository(db);
+	return {
+		staleGenerations: await repo.deleteStaleGenerationsOlderThan(cutoff, GC_BATCH_LIMIT),
+		abandonedGenerations: await repo.deleteAbandonedGenerationsOlderThan(cutoff, GC_BATCH_LIMIT),
+		orphanOccurrences: await repo.deleteOrphanOccurrencesOlderThan(cutoff, GC_BATCH_LIMIT),
+	};
+}

package/src/object-cache/index.ts

@@ -131,6 +131,8 @@ function raceInFlightEpochRead(
 const BACKEND_KEY = Symbol.for("emdash:object-cache:backend");
 const EPOCH_KEY = Symbol.for("emdash:object-cache:epochs");
 const PENDING_KEY = Symbol.for("emdash:object-cache:pending-bumps");
+const LAST_CONTENT_WRITE_KEY = Symbol.for("emdash:object-cache:last-content-write");
+const PENDING_CONTENT_WRITE_KEY = Symbol.for("emdash:object-cache:pending-content-write");
 const g = globalThis as Record<symbol, unknown>;
 
 const holder: BackendHolder =
@@ -171,6 +173,39 @@ const pendingBumps: Set<string> =
 		return s;
 	})();
 
+/**
+ * Isolate-local ms-epoch of the last content-namespace invalidation, plus a
+ * cached backend read (same revalidate window as epochs). Adapters that need
+ * to prefer fresh SQL after a publish (e.g. Hyperdrive `cachedBinding`) read
+ * this via {@link getLastContentWriteAt}.
+ */
+interface LastContentWriteState {
+	/** Local / merged stamp; 0 if never set in this isolate. */
+	value: number;
+	/** `Date.now()` when `value` was last confirmed from the backend (or local stamp). */
+	at: number;
+	promise?: Promise<number>;
+	promiseAt?: number;
+}
+
+const lastContentWrite: LastContentWriteState =
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis singleton pattern (see request-context.ts)
+	(g[LAST_CONTENT_WRITE_KEY] as LastContentWriteState | undefined) ??
+	(() => {
+		const s: LastContentWriteState = { value: 0, at: 0 };
+		g[LAST_CONTENT_WRITE_KEY] = s;
+		return s;
+	})();
+
+/** Whether a backend persist of the content-write stamp is already scheduled. */
+const contentWritePersist: { pending: boolean } =
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis singleton pattern (see request-context.ts)
+	(g[PENDING_CONTENT_WRITE_KEY] as { pending: boolean } | undefined) ??
+	(() => {
+		const s = { pending: false };
+		g[PENDING_CONTENT_WRITE_KEY] = s;
+		return s;
+	})();
 /**
  * Resolve (once per isolate) the configured object-cache backend.
  *
@@ -246,6 +281,11 @@ export function __setObjectCacheBackendForTests(
 	holder.backend = backend;
 	holder.config = { ...holder.config, ...config };
 	epochCache.clear();
+	lastContentWrite.value = 0;
+	lastContentWrite.at = 0;
+	lastContentWrite.promise = undefined;
+	lastContentWrite.promiseAt = undefined;
+	contentWritePersist.pending = false;
 }
 
 /** Build the backend key for a namespace's epoch anchor. */
@@ -253,6 +293,14 @@ function epochKey(namespace: string): string {
 	return `${holder.config.keyPrefix}:epoch:${namespace}`;
 }
 
+/** Backend key for the shared "last content write" stamp (no short TTL). */
+function lastContentWriteKey(): string {
+	return `${holder.config.keyPrefix}:last-content-write-at`;
+}
+
+function isContentNamespace(namespace: string): boolean {
+	return namespace.startsWith("content:");
+}
 /**
  * Build the (epoch-independent) backend key for a cached value.
  *
@@ -469,6 +517,95 @@ export async function isObjectCacheActive(): Promise<boolean> {
 	return backend !== null && !shouldBypass();
 }
 
+/**
+ * Stamp the isolate-local + backend "last content write" marker when a
+ * content collection namespace is invalidated. Used by DB adapters (Hyperdrive)
+ * to briefly prefer uncached SQL after a publish so edge/object caches are not
+ * reseeded from a stale query-cache hit.
+ */
+function stampLastContentWrite(): void {
+	const stamp = Math.max(lastContentWrite.value + 1, Date.now());
+	lastContentWrite.value = stamp;
+	lastContentWrite.at = stamp;
+	// Drop any in-flight backend read so it cannot lower a fresher local stamp.
+	lastContentWrite.promise = undefined;
+	lastContentWrite.promiseAt = undefined;
+
+	if (contentWritePersist.pending) return;
+	contentWritePersist.pending = true;
+	after(async () => {
+		contentWritePersist.pending = false;
+		try {
+			const backend = await getBackend();
+			if (!backend) return;
+			const latest = lastContentWrite.value;
+			// Persistent (no TTL) — same contract as epoch anchors.
+			await backend.set(lastContentWriteKey(), String(latest));
+		} catch (error) {
+			console.error("[object-cache] last-content-write stamp failed:", error);
+		}
+	});
+}
+
+/**
+ * ms-epoch of the last content-namespace invalidation (`content:*`), or `0`
+ * if unknown. Returns `max(local, backend)` so a warm isolate that just
+ * published is immediately correct, and cold isolates learn within their
+ * `revalidate` window after another isolate stamped the backend.
+ */
+export async function getLastContentWriteAt(): Promise<number> {
+	const local = lastContentWrite.value;
+	const now = Date.now();
+	// Cache a confirmed miss (`0`) the same way as a positive stamp — otherwise
+	// every logged-out request re-reads the backend until the first content write.
+	if (now - lastContentWrite.at < holder.config.revalidate) {
+		return local;
+	}
+
+	const backend = await getBackend();
+	if (!backend) return local;
+
+	if (lastContentWrite.promise) {
+		const age = now - (lastContentWrite.promiseAt ?? 0);
+		const deadline = epochReadDeadline();
+		if (age < deadline) {
+			return raceInFlightEpochRead(lastContentWrite.promise, deadline - age, local);
+		}
+	}
+
+	const promise = (async () => {
+		let value: number;
+		try {
+			const raw = await withTimeout(
+				backend.get(lastContentWriteKey()),
+				holder.config.timeout,
+				"last-content-write read",
+			);
+			const parsed = raw === null ? 0 : Number(raw);
+			value = Number.isFinite(parsed) ? parsed : 0;
+		} catch {
+			value = lastContentWrite.value;
+		}
+		const merged = Math.max(value, lastContentWrite.value);
+		lastContentWrite.value = merged;
+		lastContentWrite.at = Date.now();
+		lastContentWrite.promise = undefined;
+		lastContentWrite.promiseAt = undefined;
+		return merged;
+	})();
+
+	after(() =>
+		promise.then(
+			() => undefined,
+			() => undefined,
+		),
+	);
+
+	lastContentWrite.promise = promise;
+	lastContentWrite.promiseAt = now;
+	return promise;
+}
+
 /**
  * Invalidate every cached value in `namespace` by bumping its epoch.
  *
@@ -476,6 +613,8 @@ export async function isObjectCacheActive(): Promise<boolean> {
  * writing isolate is instantly consistent) and the backend write is deferred
  * via `after`. Other isolates pick up the new epoch within their `revalidate`
  * window. No-ops when the cache is disabled.
+ *
+ * Content namespaces (`content:*`) also stamp {@link getLastContentWriteAt}.
  */
 export function invalidateObjectCache(namespace: string): void {
 	// Monotonic so two writes in the same millisecond still produce distinct
@@ -486,6 +625,10 @@ export function invalidateObjectCache(namespace: string): void {
 	// Optimistic local bump: keep this isolate consistent without a round-trip.
 	epochCache.set(namespace, { value: stamp, at: stamp });
 
+	if (isContentNamespace(namespace)) {
+		stampLastContentWrite();
+	}
+
 	// Coalesce repeated bumps of the same namespace within a tick (e.g. a bulk
 	// publish loop) into a single backend write that persists the latest epoch.
 	if (pendingBumps.has(namespace)) return;
@@ -504,7 +647,6 @@ export function invalidateObjectCache(namespace: string): void {
 		}
 	});
 }
-
 /**
  * Fixed namespaces for data shared across collections. Content reads fold the
  * `BYLINES` and `TAXONOMIES` epochs into their keys (via {@link cachedQuery})
@@ -525,15 +667,28 @@ export const CacheNamespace = {
 
 /** Namespace for a content collection's cached queries. */
 export function contentNamespace(collection: string): string {
+	return `content:v2:${collection}`;
+}
+
+function legacyContentNamespace(collection: string): string {
 	return `content:${collection}`;
 }
 
+/**
+ * Content epochs carried by current cache entries. The legacy epoch keeps
+ * invalidation compatible with publishers from the previous release during a
+ * rolling deployment; the versioned epoch makes old cached values unreachable.
+ */
+export function contentCacheNamespaces(collection: string): readonly string[] {
+	return [contentNamespace(collection), legacyContentNamespace(collection)];
+}
+
 /**
  * Namespaces a content read depends on: the collection itself plus the shared
  * byline/taxonomy data folded into each entry.
  */
 export function contentNamespaces(collection: string): readonly string[] {
-	return [contentNamespace(collection), CacheNamespace.BYLINES, CacheNamespace.TAXONOMIES];
+	return [...contentCacheNamespaces(collection), CacheNamespace.BYLINES, CacheNamespace.TAXONOMIES];
 }
 
 /**
@@ -541,7 +696,9 @@ export function contentNamespaces(collection: string): readonly string[] {
  * Call from every write path that mutates rows in `ec_<collection>`.
  */
 export function invalidateCollectionCache(collection: string): void {
-	invalidateObjectCache(contentNamespace(collection));
+	for (const namespace of contentCacheNamespaces(collection)) {
+		invalidateObjectCache(namespace);
+	}
 }
 
 /** Invalidate cached taxonomy definitions/terms and all content that hydrates them. */

package/src/plugins/routes.ts

@@ -82,6 +82,40 @@ export function buildRouteMeta(route: {
 	return meta;
 }
 
+/**
+ * HTTP methods that carry a request body. Everything else (GET, HEAD, DELETE)
+ * takes its route input from the URL query string.
+ */
+const BODY_METHODS = new Set(["POST", "PUT", "PATCH"]);
+
+/**
+ * Parse a plugin route's input from the request, by method.
+ *
+ * Body methods (POST/PUT/PATCH) parse the JSON body as before. Bodyless
+ * methods (GET/HEAD/DELETE) have no body, so `request.json()` resolves to
+ * undefined and fails schema validation (#2146) — parse the query string into
+ * an object instead. Repeated keys (`?tag=a&tag=b`) become an array so array
+ * schemas work; a single key stays a scalar.
+ */
+export async function parseRouteInput(request: Request): Promise<unknown> {
+	if (BODY_METHODS.has(request.method.toUpperCase())) {
+		try {
+			return await request.json();
+		} catch {
+			// No body or not JSON
+			return undefined;
+		}
+	}
+
+	const params = new URL(request.url).searchParams;
+	const input: Record<string, string | string[]> = {};
+	for (const key of new Set(params.keys())) {
+		const values = params.getAll(key);
+		input[key] = values.length > 1 ? values : values[0];
+	}
+	return input;
+}
+
 /**
  * Result from a route invocation
  */

package/src/plugins/storage-indexes.ts

@@ -12,9 +12,9 @@ import { sql } from "kysely";
 import { jsonExtractExpr, isPostgres } from "../database/dialect-helpers.js";
 import type { Database } from "../database/types.js";
 import {
-	validateIdentifier,
 	validateJsonFieldName,
 	validatePluginIdentifier,
+	validateStorageCollectionName,
 } from "../database/validate.js";
 
 /**
@@ -36,8 +36,10 @@ export function generateIndexName(
 /**
  * Generate a Kysely sql expression for creating an expression index.
  *
- * Validates all identifiers before interpolation to prevent SQL injection.
- * Plugin ID and collection values are parameterized in the WHERE clause.
+ * Validates all inputs before interpolation. The collection uses the
+ * permissive manifest-key rules rather than SQL-identifier rules — it is
+ * stored as opaque text and only reaches SQL inside the generated index
+ * name — so kebab-case collections index like any other.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance
 export function generateCreateIndexSql(
@@ -47,9 +49,8 @@ export function generateCreateIndexSql(
 	fields: string[],
 	options?: { unique?: boolean },
 ): RawBuilder<unknown> {
-	// Validate all identifiers
 	validatePluginIdentifier(pluginId, "plugin ID");
-	validateIdentifier(collection, "collection name");
+	validateStorageCollectionName(collection, "collection name");
 	for (const field of fields) {
 		validateJsonFieldName(field, "index field name");
 	}
@@ -68,14 +69,15 @@ export function generateCreateIndexSql(
 		})
 		.join(", ");
 
-	// Partial index filtered to this plugin/collection
-	// SQLite prohibits bound parameters in partial index WHERE clauses,
-	// so we use sql.lit() for literal string values. Both pluginId and
-	// collection are validated above, so this is safe.
+	// Composite non-partial index: the leading (plugin_id, collection) columns
+	// scope it per plugin/collection — including unique-index semantics — and
+	// let it serve the repository's bound-parameter WHERE plus the JSON
+	// expression ORDER BY. A partial index (WHERE plugin_id = 'x' AND
+	// collection = 'y') is never chosen by SQLite under bound parameters
+	// unless ANALYZE has run, and D1 never runs ANALYZE.
 	const createKeyword = options?.unique ? "CREATE UNIQUE INDEX" : "CREATE INDEX";
 	return sql`${sql.raw(createKeyword)} IF NOT EXISTS ${sql.ref(indexName)}
-		ON _plugin_storage(${sql.raw(expressions)})
-		WHERE plugin_id = ${sql.lit(pluginId)} AND collection = ${sql.lit(collection)}
+		ON _plugin_storage(plugin_id, collection, ${sql.raw(expressions)})
 	`;
 }
 
@@ -254,6 +256,43 @@ export async function syncStorageIndexes(
 	};
 }
 
+/**
+ * Materialize the storage indexes a set of plugins declare in their
+ * manifests. Failures are logged per collection and never thrown — a missing
+ * index affects query performance, not correctness, so it must not fail an
+ * install or a scheduler tick.
+ */
+export async function syncDeclaredStorageIndexes(
+	db: Kysely<Database>,
+	plugins: Array<{
+		id: string;
+		storage?: Record<
+			string,
+			{ indexes: Array<string | string[]>; uniqueIndexes?: Array<string | string[]> }
+		>;
+	}>,
+): Promise<void> {
+	for (const plugin of plugins) {
+		for (const [collection, config] of Object.entries(plugin.storage ?? {})) {
+			try {
+				const result = await syncStorageIndexes(db, plugin.id, collection, config.indexes, {
+					uniqueIndexes: config.uniqueIndexes,
+				});
+				for (const failure of result.errors) {
+					console.error(
+						`[plugins] Failed to sync storage index ${failure.index} for ${plugin.id}/${collection}: ${failure.error}`,
+					);
+				}
+			} catch (error) {
+				console.error(
+					`[plugins] Failed to sync storage indexes for ${plugin.id}/${collection}:`,
+					error,
+				);
+			}
+		}
+	}
+}
+
 /**
  * Remove all indexes for a plugin
  */