emdash 0.37.0 → 0.38.0

package/src/media/usage/content-refresh.ts

@@ -868,6 +868,7 @@ export async function findNonTranslatableSiblingContentIds(
 	updatedContentId: string,
 	translationGroup: string | null | undefined,
 	updatedData: Record<string, unknown> | undefined,
+	options: { absentAsCleared?: boolean } = {},
 ): Promise<string[]> {
 	if (!isI18nEnabled() || !updatedData || !translationGroup) return [];
 
@@ -887,7 +888,7 @@ export async function findNonTranslatableSiblingContentIds(
 		.execute();
 
 	const touchedNonTranslatableSlugs = fields
-		.filter((field) => field.slug in updatedData)
+		.filter((field) => options.absentAsCleared || field.slug in updatedData)
 		.map((field) => field.slug);
 	if (touchedNonTranslatableSlugs.length === 0) return [];
 

package/src/menus/index.ts

@@ -14,7 +14,7 @@ import { sql } from "kysely";
 import { menuTag } from "../cache/chrome-tags.js";
 import type { Database } from "../database/types.js";
 import { validateIdentifier } from "../database/validate.js";
-import { resolveLocale, resolveLocaleChain } from "../i18n/resolve.js";
+import { interpolateUrlPattern, resolveLocale, resolveLocaleChain } from "../i18n/resolve.js";
 import { getDb } from "../loader.js";
 import { cachedQuery, CacheNamespace } from "../object-cache/index.js";
 import type { CacheHint } from "../query.js";
@@ -332,21 +332,10 @@ function resolveMenuItem(
 	};
 }
 
-const SLUG_PLACEHOLDER = /\{slug\}/g;
-const ID_PLACEHOLDER = /\{id\}/g;
-
-/**
- * Interpolate a URL pattern with entry data
- *
- * Replaces `{slug}` and `{id}` placeholders.
- */
-function interpolateUrlPattern(pattern: string, slug: string, id: string): string {
-	return pattern.replace(SLUG_PLACEHOLDER, slug).replace(ID_PLACEHOLDER, id);
-}
-
 interface ContentReferenceRow {
 	id: string;
 	slug: string;
+	published_at: string | null;
 	locale: string;
 	translation_group: string;
 }
@@ -354,6 +343,7 @@ interface ContentReferenceRow {
 interface ResolvedContentReference {
 	id: string;
 	slug: string;
+	publishedAt: string | null;
 }
 
 type ContentReferenceLookup = Map<string, Map<string, ResolvedContentReference>>;
@@ -371,7 +361,7 @@ async function resolveContentReferences(
 				validateIdentifier(collection, "menu item collection");
 				for (const batch of chunks([...referenceGroups], SQL_BATCH_SIZE)) {
 					const result = await sql<ContentReferenceRow>`
-						SELECT id, slug, locale, translation_group
+						SELECT id, slug, published_at, locale, translation_group
 						FROM ${sql.ref(`ec_${collection}`)}
 						WHERE translation_group IN (${sql.join(batch)})
 					`.execute(db);
@@ -383,16 +373,18 @@ async function resolveContentReferences(
 					}
 				}
 				for (const [referenceGroup, row] of localized) {
-					lookup.set(referenceGroup, { id: row.id, slug: row.slug });
+					lookup.set(referenceGroup, { id: row.id, slug: row.slug, publishedAt: row.published_at });
 				}
 
 				const unresolved = [...referenceGroups].filter((id) => !lookup.has(id));
 				for (const batch of chunks(unresolved, SQL_BATCH_SIZE)) {
-					const result = await sql<ResolvedContentReference>`
-						SELECT id, slug FROM ${sql.ref(`ec_${collection}`)}
+					const result = await sql<Pick<ContentReferenceRow, "id" | "slug" | "published_at">>`
+						SELECT id, slug, published_at FROM ${sql.ref(`ec_${collection}`)}
 						WHERE id IN (${sql.join(batch)})
 					`.execute(db);
-					for (const row of result.rows) lookup.set(row.id, row);
+					for (const row of result.rows) {
+						lookup.set(row.id, { id: row.id, slug: row.slug, publishedAt: row.published_at });
+					}
 				}
 			} catch (error) {
 				console.error(`Failed to resolve content URLs for ${collection}:`, error);
@@ -437,9 +429,13 @@ function resolveContentUrl(
 	if (!referenceGroup) return null;
 	const row = contentLookup.get(collection)?.get(referenceGroup);
 	if (!row) return null;
-	const pattern = urlPatterns.get(collection);
-	if (pattern) return interpolateUrlPattern(pattern, row.slug, row.id);
-	return `/${collection}/${row.slug}`;
+	return interpolateUrlPattern({
+		pattern: urlPatterns.get(collection) ?? null,
+		collection,
+		slug: row.slug,
+		id: row.id,
+		date: row.publishedAt,
+	});
 }
 
 interface TaxonomyReferenceRow {

package/src/page/seo-contributions.ts

@@ -5,15 +5,22 @@
  * `[...plugin, ...site, ...base]` and feeds it to `resolvePageMetadata()`,
  * which is first-wins. That ordering means plugin contributions override
  * site-level ones override base ones for any given key — base values are
- * the fallback, not the source of truth.
+ * the fallback, not the source of truth. For content pages, the entry's
+ * SEO panel values are overlaid onto the page context before the base
+ * contributions (and JSON-LD) are generated, so editor-set values
+ * override the template-provided fields.
  *
  * This replaces the per-template SEO.astro components, eliminating
  * the class of XSS bugs where templates hand-rolled JSON-LD serialization.
  */
 
+import type { ContentSeo } from "../database/repositories/types.js";
 import type { PageMetadataContribution, PublicPageContext } from "../plugins/types.js";
+import { buildSeoImageUrl, resolveSeoCanonicalUrl } from "../seo/media-url.js";
+import { getSiteSettings } from "../settings/index.js";
 import type { SeoSettings } from "../settings/types.js";
 import { buildBlogPostingJsonLd, buildWebSiteJsonLd } from "./jsonld.js";
+import { peekSeoPanel } from "./seo-panel.js";
 
 /**
  * Generate base metadata contributions from a page context's SEO data.
@@ -147,6 +154,76 @@ export function generateBaseSeoContributions(
 	return contributions;
 }
 
+/**
+ * Resolve the page context for rendering: overlay the entry's SEO panel
+ * values when they were primed for this request.
+ *
+ * Used by `<EmDashHead>`, `<EmDashBodyStart>`, and `<EmDashBodyEnd>` so
+ * head tags, JSON-LD, and every plugin hook — head and body fragments
+ * alike — see the same overlaid context. Returns the context unchanged
+ * for non-content pages or when nothing was primed. The peek is a
+ * request-cache read; site settings are only consulted when a panel
+ * exists (and are request-cached themselves), so this adds no queries.
+ */
+export async function resolveSeoPanelPage(
+	page: PublicPageContext,
+	siteUrl?: string,
+): Promise<PublicPageContext> {
+	if (!page.content) return page;
+	const seo = await peekSeoPanel(page.content.collection, page.content.id);
+	if (!seo) return page;
+	const resolvedSiteUrl =
+		siteUrl ||
+		page.siteUrl ||
+		(await getSiteSettings()).url ||
+		(URL.canParse(page.url) ? new URL(page.url).origin : "");
+	return applySeoPanelToPageContext(page, seo, { siteUrl: resolvedSiteUrl });
+}
+
+/**
+ * Overlay a content entry's SEO panel data onto the page context.
+ *
+ * `<EmDashHead>` applies this overlay before anything consumes the context:
+ * editor-set panel values override whatever the template passed in, and
+ * because the overlaid context feeds plugin hooks, the base contributions,
+ * and the JSON-LD builders alike, structured data and head tags always
+ * agree. Plugins still override the rendered output via first-wins dedup.
+ *
+ * The `<title>` element itself stays the template's responsibility —
+ * head components can't replace it — so `seo.title` feeds
+ * `og:title` / `twitter:title` / the JSON-LD headline only. Templates that
+ * want the panel title in `<title>` keep using `getSeoMeta()`.
+ *
+ * Unset panel fields fall back to the template-provided values, so pages
+ * without SEO data are unaffected.
+ */
+export function applySeoPanelToPageContext(
+	page: PublicPageContext,
+	seo: ContentSeo,
+	options: { siteUrl?: string | null } = {},
+): PublicPageContext {
+	const siteUrl = options.siteUrl ?? undefined;
+	const image = seo.image ? buildSeoImageUrl(seo.image, siteUrl) : null;
+	const canonical = seo.canonical ? resolveSeoCanonicalUrl(seo.canonical, siteUrl) : null;
+
+	return {
+		...page,
+		description: seo.description || page.description,
+		canonical: canonical || page.canonical,
+		// Mirror the resolved image into the top-level field too, so consumers
+		// reading page.image (e.g. page:metadata hooks) agree with og:image and
+		// the JSON-LD graph.
+		image: image || page.image,
+		seo: {
+			...page.seo,
+			ogTitle: seo.title || page.seo?.ogTitle,
+			ogDescription: seo.description || page.seo?.ogDescription,
+			ogImage: image || page.seo?.ogImage,
+			robots: seo.noIndex ? "noindex, nofollow" : page.seo?.robots,
+		},
+	};
+}
+
 /**
  * Generate site-level SEO metadata contributions from SiteSettings.seo.
  *

package/src/page/seo-panel.ts

@@ -0,0 +1,47 @@
+/**
+ * Request-scoped hand-off of SEO panel data from the entry query to the
+ * render components.
+ *
+ * The loader's single-entry path already folds the `_emdash_seo` row into
+ * the entry query as a JSON subselect, so the panel data is in hand when an
+ * entry is fetched — it primes this cache, and `<EmDashHead>` (plus the body
+ * fragment components) pick the data up with a plain map read. No code path
+ * here ever queries the database.
+ *
+ * Kept as a leaf module (request-cache only) so the loader and the query
+ * layer can prime without importing the page-context machinery, which pulls
+ * in site settings and would create an import cycle back into the loader.
+ */
+
+import type { ContentSeo } from "../database/repositories/types.js";
+import { peekRequestCache, setRequestCacheEntry } from "../request-cache.js";
+
+function seoPanelCacheKey(collection: string, id: string): string {
+	return `seo-panel:${collection}:${id}`;
+}
+
+/**
+ * Prime the request-scoped SEO panel cache for a content entry.
+ *
+ * Called wherever an entry's folded SEO data materializes: the loader's
+ * single-entry path (fresh query) and the object-cache revive path in
+ * `getEmDashEntry` (warm hit, where the loader never runs). No-ops outside
+ * a request context; never overwrites an already-primed value.
+ */
+export function primeSeoPanel(collection: string, id: string, seo: ContentSeo): void {
+	setRequestCacheEntry(seoPanelCacheKey(collection, id), seo);
+}
+
+/**
+ * Read the SEO panel data primed for a content entry in this request.
+ *
+ * Returns `null` when nothing was primed — either the entry has no SEO
+ * row, or it was not fetched through an EmDash loader in this request
+ * (e.g. prerendered pages, or a hand-rolled query). Callers treat null as
+ * "no overlay"; this never falls back to a database lookup, so the
+ * logged-out hot path gains zero queries.
+ */
+export async function peekSeoPanel(collection: string, id: string): Promise<ContentSeo | null> {
+	const primed = peekRequestCache<ContentSeo>(seoPanelCacheKey(collection, id));
+	return primed ? await primed : null;
+}

package/src/plugin-types.ts

@@ -43,6 +43,7 @@ import type { ZodType } from "zod";
 
 import type { SandboxHookErrorEnvelope } from "./plugins/sandbox/hook-result.js";
 import type {
+	ActorInfo,
 	CommentAfterCreateEvent,
 	CommentAfterCreateHandler,
 	CommentAfterModerateEvent,
@@ -262,6 +263,7 @@ export interface SandboxedContentBeforeSaveConfig extends Omit<
 }
 
 export type { SandboxHookErrorEnvelope };
+export type { NumericDelta, UpdateIfArgs, UpdateIfResult } from "./plugins/types.js";
 
 /**
  * Re-export of event types so plugin authors can reference them
@@ -272,6 +274,7 @@ export type { SandboxHookErrorEnvelope };
  * portable `.d.mts`.
  */
 export type {
+	ActorInfo,
 	CommentAfterCreateEvent,
 	CommentAfterModerateEvent,
 	CommentBeforeCreateEvent,
@@ -294,3 +297,9 @@ export type {
 	PluginContext,
 	UninstallEvent,
 };
+
+export type {
+	VersionedValue,
+	ConditionalWriteResult,
+	ConditionalDeleteResult,
+} from "./plugins/types.js";

package/src/plugins/conditional-storage.ts

@@ -0,0 +1,30 @@
+const MAX_KEY_LENGTH = 1024;
+const MAX_REVISION_LENGTH = 128;
+const MAX_VALUE_BYTES = 1024 * 1024;
+
+export function assertStorageKey(key: unknown, maxLength = MAX_KEY_LENGTH): asserts key is string {
+	if (typeof key !== "string" || key.length === 0 || key.length > maxLength) {
+		throw new TypeError(`Storage key must be a nonempty string of at most ${maxLength} characters`);
+	}
+}
+
+export function assertStorageRevision(revision: unknown): asserts revision is string {
+	if (
+		typeof revision !== "string" ||
+		revision.length === 0 ||
+		revision.length > MAX_REVISION_LENGTH
+	) {
+		throw new TypeError("Storage revision must be a nonempty string of at most 128 characters");
+	}
+}
+
+export function serializeConditionalValue(value: unknown): string {
+	const serialized = JSON.stringify(value);
+	if (serialized === undefined) {
+		throw new TypeError("Storage value must be JSON serializable");
+	}
+	if (new TextEncoder().encode(serialized).byteLength > MAX_VALUE_BYTES) {
+		throw new TypeError("Conditional storage value must not exceed 1 MiB of JSON");
+	}
+	return serialized;
+}

package/src/plugins/context.ts

@@ -9,6 +9,7 @@ import type { Kysely } from "kysely";
 import { ulid } from "ulidx";
 
 import { ContentRepository } from "../database/repositories/content.js";
+import { EntryLockRepository } from "../database/repositories/entry-locks.js";
 import { MediaRepository } from "../database/repositories/media.js";
 import { OptionsRepository } from "../database/repositories/options.js";
 import { PluginStorageRepository } from "../database/repositories/plugin-storage.js";
@@ -27,6 +28,7 @@ import { enrichImageMetadata } from "../media/enrich.js";
 import { markContentMediaUsageCollectionStaleSafely } from "../media/usage/content-refresh.js";
 import { invalidateSiteSettingsCache } from "../settings/index.js";
 import type { Storage } from "../storage/types.js";
+import { assertStorageKey } from "./conditional-storage.js";
 import { CronAccessImpl } from "./cron.js";
 import type { EmailPipeline } from "./email.js";
 import type {
@@ -76,6 +78,18 @@ export function createKVAccess(optionsRepo: OptionsRepository, pluginId: string)
 		async get<T>(key: string): Promise<T | null> {
 			return optionsRepo.get<T>(`${prefix}${key}`);
 		},
+		async getVersioned<T>(key: string) {
+			assertStorageKey(key);
+			return optionsRepo.getVersioned<T>(`${prefix}${key}`);
+		},
+		async compareAndSet(key, expectedRevision, value) {
+			assertStorageKey(key);
+			return optionsRepo.compareAndSet(`${prefix}${key}`, expectedRevision, value);
+		},
+		async compareAndDelete(key, expectedRevision) {
+			assertStorageKey(key);
+			return optionsRepo.compareAndDelete(`${prefix}${key}`, expectedRevision);
+		},
 
 		async set(key: string, value: unknown): Promise<void> {
 			await optionsRepo.set(`${prefix}${key}`, value);
@@ -118,6 +132,9 @@ function createStorageCollection<T>(
 
 	return {
 		get: (id) => repo.get(id),
+		getVersioned: (id) => repo.getVersioned(id),
+		compareAndSet: (id, expectedRevision, data) => repo.compareAndSet(id, expectedRevision, data),
+		compareAndDelete: (id, expectedRevision) => repo.compareAndDelete(id, expectedRevision),
 		put: (id, data) => repo.put(id, data),
 		delete: (id) => repo.delete(id),
 		exists: (id) => repo.exists(id),
@@ -125,6 +142,7 @@ function createStorageCollection<T>(
 		putMany: (items) => repo.putMany(items),
 		deleteMany: (ids) => repo.deleteMany(ids),
 		count: (where) => repo.count(where),
+		updateIf: (id, updateArgs) => repo.updateIf(id, updateArgs),
 
 		// Query returns PaginatedResult instead of the old format
 		async query(options?: QueryOptions): Promise<PaginatedResult<{ id: string; data: T }>> {
@@ -500,6 +518,9 @@ export function createContentAccessWithWrite(
 			const contentRepo = new ContentRepository(db);
 			const deleted = await contentRepo.delete(collection, id);
 			if (deleted) {
+				// A trashed entry can no longer be opened, so its holder can never
+				// release the lease itself. Mirrors handleContentDelete.
+				await new EntryLockRepository(db).releaseEntry(collection, id);
 				await markContentMediaUsageCollectionStaleSafely(db, collection, "CONTENT_USAGE_STALE");
 			}
 			return deleted;
@@ -706,11 +727,31 @@ function isHostAllowed(host: string, allowedHosts: string[]): boolean {
 	});
 }
 
+function tryParsePluginHttpTarget(url: string): URL | null {
+	try {
+		return new URL(url);
+	} catch {
+		return null;
+	}
+}
+
+async function validatePluginHttpTarget(pluginId: string, url: string): Promise<URL> {
+	try {
+		return await resolveAndValidateExternalUrl(url);
+	} catch (error) {
+		const message = error instanceof SsrfError ? error.message : "SSRF validation failed";
+		const target = tryParsePluginHttpTarget(url);
+		throw new Error(
+			`Plugin "${pluginId}": blocked fetch to "${target ? target.hostname : "invalid URL"}": ${message}`,
+			{ cause: error },
+		);
+	}
+}
+
 /**
- * Create HTTP access with host validation.
+ * Create HTTP access with host validation and SSRF protection.
  *
- * Uses redirect: "manual" to re-validate each redirect target against
- * the allowedHosts list, preventing redirects to unauthorized hosts.
+ * Uses redirect: "manual" to re-validate each redirect target before dispatch.
  */
 export function createHttpAccess(pluginId: string, allowedHosts: string[]): HttpAccess {
 	return {
@@ -727,13 +768,14 @@ export function createHttpAccess(pluginId: string, allowedHosts: string[]): Http
 			let currentInit = init;
 
 			for (let i = 0; i <= MAX_PLUGIN_REDIRECTS; i++) {
-				const hostname = new URL(currentUrl).hostname;
-				if (!isHostAllowed(hostname, allowedHosts)) {
+				const target = tryParsePluginHttpTarget(currentUrl);
+				if (target && !isHostAllowed(target.hostname, allowedHosts)) {
 					throw new Error(
-						`Plugin "${pluginId}" is not allowed to fetch from host "${hostname}". ` +
+						`Plugin "${pluginId}" is not allowed to fetch from host "${target.hostname}". ` +
 							`Allowed hosts: ${allowedHosts.join(", ")}`,
 					);
 				}
+				await validatePluginHttpTarget(pluginId, currentUrl);
 
 				const response = await globalThis.fetch(currentUrl, {
 					...currentInit,
@@ -778,17 +820,7 @@ export function createUnrestrictedHttpAccess(pluginId: string): HttpAccess {
 			let currentInit = init;
 
 			for (let i = 0; i <= MAX_PLUGIN_REDIRECTS; i++) {
-				// Validate each URL against SSRF rules (private IPs, metadata
-				// endpoints, wildcard DNS, resolved-IP private ranges).
-				try {
-					await resolveAndValidateExternalUrl(currentUrl);
-				} catch (e) {
-					const msg = e instanceof SsrfError ? e.message : "SSRF validation failed";
-					throw new Error(
-						`Plugin "${pluginId}": blocked fetch to "${new URL(currentUrl).hostname}": ${msg}`,
-						{ cause: e },
-					);
-				}
+				await validatePluginHttpTarget(pluginId, currentUrl);
 
 				const response = await globalThis.fetch(currentUrl, {
 					...currentInit,

package/src/plugins/hooks.ts

@@ -15,6 +15,7 @@ import type {
 	ResolvedPlugin,
 	ResolvedHook,
 	PluginContext,
+	ActorInfo,
 	ContentHookEvent,
 	ContentDeleteEvent,
 	ContentStateChangeEvent,
@@ -488,13 +489,15 @@ export class HookPipeline {
 	/**
 	 * Run content:beforeSave hooks
 	 * Returns modified content from the pipeline. `id` is the existing item's
-	 * ID when updating.
+	 * ID when updating. `actor` is the authenticated user that triggered the
+	 * save, when one is available.
 	 */
 	async runContentBeforeSave(
 		content: Record<string, unknown>,
 		collection: string,
 		isNew: boolean,
 		id?: string,
+		actor?: ActorInfo,
 	): Promise<{
 		content: Record<string, unknown>;
 		results: HookResult<Record<string, unknown>>[];
@@ -511,6 +514,7 @@ export class HookPipeline {
 				isNew,
 			};
 			if (id !== undefined) event.id = id;
+			if (actor !== undefined) event.actor = { ...actor };
 			const ctx = this.getContext(hook.pluginId);
 			const start = Date.now();
 
@@ -550,6 +554,7 @@ export class HookPipeline {
 		content: Record<string, unknown>,
 		collection: string,
 		isNew: boolean,
+		actor?: ActorInfo,
 	): Promise<HookResult<void>[]> {
 		const hooks = this.getTypedHooks("content:afterSave");
 		const results: HookResult<void>[] = [];
@@ -557,6 +562,7 @@ export class HookPipeline {
 		for (const hook of hooks) {
 			const { handler } = hook;
 			const event: ContentHookEvent = { content, collection, isNew };
+			if (actor !== undefined) event.actor = { ...actor };
 			const ctx = this.getContext(hook.pluginId);
 			const start = Date.now();
 

package/src/plugins/index.ts

@@ -101,6 +101,8 @@ export type {
 	SandboxSaveRejectedError,
 } from "./sandbox/index.js";
 
+export { StorageSerializationError } from "./storage-query.js";
+
 // Types
 export type {
 	// Core types
@@ -118,6 +120,12 @@ export type {
 	// Context APIs
 	PluginContext,
 	StorageCollection,
+	NumericDelta,
+	UpdateIfArgs,
+	UpdateIfResult,
+	VersionedValue,
+	ConditionalWriteResult,
+	ConditionalDeleteResult,
 	KVAccess,
 	ContentAccess,
 	ContentAccessWithWrite,
@@ -145,6 +153,7 @@ export type {
 	HookName,
 	ResolvedHook,
 	ResolvedPluginHooks,
+	ActorInfo,
 	ContentHookEvent,
 	ContentDeleteEvent,
 	ContentPublishStateChangeEvent,

package/src/plugins/manager.ts

@@ -26,6 +26,7 @@ import {
 } from "./hooks.js";
 import { PluginRouteRegistry, type RouteResult, type InvokeRouteOptions } from "./routes.js";
 import type {
+	ActorInfo,
 	PluginDefinition,
 	ResolvedPlugin,
 	PluginStorageConfig,
@@ -306,12 +307,13 @@ export class PluginManager {
 		collection: string,
 		isNew: boolean,
 		id?: string,
+		actor?: ActorInfo,
 	): Promise<{
 		content: Record<string, unknown>;
 		results: HookResult<Record<string, unknown>>[];
 	}> {
 		this.ensureInitialized();
-		return this.hookPipeline!.runContentBeforeSave(content, collection, isNew, id);
+		return this.hookPipeline!.runContentBeforeSave(content, collection, isNew, id, actor);
 	}
 
 	/**
@@ -321,9 +323,10 @@ export class PluginManager {
 		content: Record<string, unknown>,
 		collection: string,
 		isNew: boolean,
+		actor?: ActorInfo,
 	): Promise<HookResult<void>[]> {
 		this.ensureInitialized();
-		return this.hookPipeline!.runContentAfterSave(content, collection, isNew);
+		return this.hookPipeline!.runContentAfterSave(content, collection, isNew, actor);
 	}
 
 	/**

package/src/plugins/sandbox/types.ts

@@ -236,6 +236,15 @@ export interface SandboxRunner {
 	 */
 	isHealthy(): boolean;
 
+	/**
+	 * Why the runner cannot run plugins, once isAvailable() or isHealthy()
+	 * has returned false. A lowercase clause without a final period: callers
+	 * append it to their own message after a colon.
+	 *
+	 * Making this required breaks runners implemented outside this repository.
+	 */
+	unavailableReason?(): string;
+
 	/**
 	 * Load a sandboxed plugin from code.
 	 *
@@ -260,6 +269,11 @@ export interface SandboxRunner {
 	terminateAll(): Promise<void>;
 }
 
+export function withUnavailableReason(message: string, runner: SandboxRunner | null): string {
+	const reason = runner?.unavailableReason?.();
+	return reason ? `${message}: ${reason}` : message;
+}
+
 /**
  * Error thrown when the sandbox runtime is unavailable.
  * This happens when the sidecar process has crashed or hasn't started.
@@ -273,11 +287,11 @@ export class SandboxUnavailableError extends Error {
 
 /**
  * Factory function type for creating sandbox runners.
- * Exported by platform adapters (e.g., @emdash-cms/adapter-cloudflare/sandbox).
+ * Exported by platform adapters (e.g., @emdash-cms/cloudflare/sandbox).
  *
  * @example
  * ```typescript
- * // In @emdash-cms/adapter-cloudflare/sandbox.ts
+ * // In @emdash-cms/cloudflare/sandbox
  * export const createSandboxRunner: SandboxRunnerFactory = (options) => {
  *   return new CloudflareSandboxRunner(options);
  * };

package/src/plugins/storage-query.ts

@@ -25,6 +25,38 @@ export class StorageQueryError extends Error {
 	}
 }
 
+/**
+ * Error thrown when a guarded `updateIf` loses a concurrent race by aborting
+ * rather than resolving to `{ applied: false }`.
+ *
+ * `updateIf`'s `{ applied: false }` contract (row absent OR guard failed)
+ * assumes READ COMMITTED — the default. There, a losing concurrent writer
+ * re-evaluates the guard against the winner's freshly committed row and
+ * cleanly resolves to `{ applied: false }`. Two aborts escape that contract:
+ *
+ * - `40001` (serialization_failure), only above READ COMMITTED, where the
+ *   loser cannot re-read against a newer snapshot.
+ * - `40P01` (deadlock_detected), at any isolation level, when transactions
+ *   take row locks in opposite order.
+ *
+ * This error surfaces either abort so the caller can retry the write.
+ *
+ * The no-oversell SAFETY invariant holds either way: a losing writer NEVER
+ * applies its update — it either sees `{ applied: false }` or throws here.
+ */
+export class StorageSerializationError extends Error {
+	readonly code = "STORAGE_SERIALIZATION_FAILURE";
+	readonly retryable = true;
+	/** The Postgres SQLSTATE that triggered this error (`40001` / `40P01`). */
+	readonly sqlState?: string;
+
+	constructor(message: string, options?: { cause?: unknown; sqlState?: string }) {
+		super(message, { cause: options?.cause });
+		this.name = "StorageSerializationError";
+		this.sqlState = options?.sqlState;
+	}
+}
+
 /**
  * Check if a value is a range filter
  */
@@ -213,6 +245,17 @@ export function buildCondition(
 		if (value.lt !== undefined) pushBound("<", value.lt);
 		if (value.lte !== undefined) pushBound("<=", value.lte);
 
+		// A filter with no defined bound contributes no SQL. Returning it would
+		// widen the caller's predicate to "match everything" — survivable in a
+		// read, but it strips the guard off a conditional write.
+		if (conditions.length === 0) {
+			throw new StorageQueryError(
+				`Range filter for field '${field}' has no defined bound`,
+				field,
+				"Provide at least one of gt, gte, lt, or lte, or omit the field.",
+			);
+		}
+
 		return {
 			sql: conditions.join(" AND "),
 			params,
@@ -238,6 +281,8 @@ export function buildWhereClause(
 
 	for (const [field, value] of Object.entries(where)) {
 		const condition = buildCondition(db, field, value);
+		// An empty slot in the join would emit `<cond> AND ` and fail to parse.
+		if (!condition.sql) continue;
 		conditions.push(condition.sql);
 		params.push(...condition.params);
 	}