emdash 0.18.0 → 0.20.0

package/src/seed/apply.ts

@@ -115,6 +115,13 @@ export async function applySeed(
 	const seedIdMap = new Map<string, string>(); // seed id -> real entry id
 	const seedBylineIdMap = new Map<string, string>(); // seed byline id -> real byline id
 
+	// Fallback locale for rows that omit an explicit `locale`. Prefer the runtime
+	// config (runtime-driven seeds), then the seed's self-described `defaultLocale`
+	// (CLI exports run outside the runtime), and only then `en`. Without the
+	// seed-carried default, a non-`en` single-locale project would be rewritten to
+	// `en` on apply (#1421).
+	const defaultLocale = getI18nConfig()?.defaultLocale ?? seed.defaultLocale ?? "en";
+
 	// 1. Site settings
 	if (seed.settings) {
 		await setSiteSettings(seed.settings, db);
@@ -224,10 +231,9 @@ export async function applySeed(
 		// seed-local id -> resolved info, used to wire `translationOf` refs.
 		const defSeedIdMap = new Map<string, { id: string; translationGroup: string }>();
 		const termSeedIdMap = new Map<string, string>();
-		const fallbackLocale = getI18nConfig()?.defaultLocale ?? "en";
 
 		for (const taxonomy of seed.taxonomies) {
-			const defLocale = taxonomy.locale ?? fallbackLocale;
+			const defLocale = taxonomy.locale ?? defaultLocale;
 
 			// (name, locale) is the UNIQUE key after migration 036.
 			const existingDef = await db
@@ -418,8 +424,13 @@ export async function applySeed(
 		// Create content entries
 		for (const [collectionSlug, entries] of Object.entries(seed.content)) {
 			for (const entry of entries) {
+				// Resolve the entry's locale up front so a non-`en` single-locale
+				// export (which omits `locale`) is filed under the project default
+				// rather than `en` (#1421).
+				const entryLocale = entry.locale ?? defaultLocale;
+
 				// Check if entry exists (by slug + locale for locale-aware lookup)
-				const existing = await contentRepo.findBySlug(collectionSlug, entry.slug, entry.locale);
+				const existing = await contentRepo.findBySlug(collectionSlug, entry.slug, entryLocale);
 
 				if (existing) {
 					if (onConflict === "error") {
@@ -515,7 +526,7 @@ export async function applySeed(
 						slug: entry.slug,
 						status,
 						data: resolvedData,
-						locale: entry.locale,
+						locale: entryLocale,
 						translationOf,
 						publishedAt: status === "published" ? new Date().toISOString() : null,
 					});
@@ -545,10 +556,9 @@ export async function applySeed(
 		const menuSeedIdMap = new Map<string, { id: string; translationGroup: string }>();
 		// Shared across menus: translated items reference anchor items in sibling menus.
 		const itemSeedIdMap = new Map<string, { id: string; translationGroup: string }>();
-		const fallbackLocale = getI18nConfig()?.defaultLocale ?? "en";
 
 		for (const menu of seed.menus) {
-			const locale = menu.locale ?? fallbackLocale;
+			const locale = menu.locale ?? defaultLocale;
 			let lookup = db
 				.selectFrom("_emdash_menus")
 				.selectAll()

package/src/seed/types.ts

@@ -19,6 +19,15 @@ export interface SeedFile {
 	/** Seed format version */
 	version: "1";
 
+	/**
+	 * Default locale for locale-bearing rows (menus, taxonomies, content) that
+	 * omit an explicit `locale`. Lets a non-`en` single-locale project survive an
+	 * `export-seed` → `seed` round-trip: `apply` runs outside the Astro runtime
+	 * (no i18n config), so without this it would backfill the omitted locale as
+	 * `en`. See #1421.
+	 */
+	defaultLocale?: string;
+
 	/** Metadata about the seed */
 	meta?: {
 		name?: string;

package/src/seed/validate.ts

@@ -57,6 +57,21 @@ export function validateSeed(data: unknown): ValidationResult {
 		errors.push(`Unsupported seed version: ${String(seed.version)}`);
 	}
 
+	// defaultLocale backfills the locale of rows that omit one, so a blank or
+	// whitespace-padded value would silently write empty/invalid locales to the DB.
+	// Exported seeds never hit this, but it's part of the public schema now.
+	if (seed.defaultLocale !== undefined) {
+		if (
+			typeof seed.defaultLocale !== "string" ||
+			seed.defaultLocale.length === 0 ||
+			seed.defaultLocale !== seed.defaultLocale.trim()
+		) {
+			errors.push(
+				"defaultLocale: must be a non-empty string with no leading or trailing whitespace",
+			);
+		}
+	}
+
 	// Validate collections
 	if (seed.collections) {
 		if (!Array.isArray(seed.collections)) {

package/src/seo/index.ts

@@ -30,6 +30,7 @@
  */
 
 import type { ContentSeo } from "../database/repositories/types.js";
+import { buildSeoImageUrl } from "./media-url.js";
 
 const TRAILING_SLASH_RE = /\/$/;
 const ABSOLUTE_URL_RE = /^https?:\/\//i;
@@ -117,7 +118,7 @@ export function getSeoMeta<T>(content: SeoContentInput<T>, options: SeoMetaOptio
 		null;
 
 	// OG image: SEO image > default
-	const ogImage = seo.image ? buildMediaUrl(seo.image, siteUrl) : (defaultOgImage ?? null);
+	const ogImage = seo.image ? buildSeoImageUrl(seo.image, siteUrl) : (defaultOgImage ?? null);
 
 	// Canonical: explicit > path-based > null
 	let canonical: string | null = null;
@@ -159,30 +160,3 @@ export function getSeoMeta<T>(content: SeoContentInput<T>, options: SeoMetaOptio
 export function getContentSeo<T>(content: SeoContentInput<T>): ContentSeo | undefined {
 	return content.seo ?? content.data.seo;
 }
-
-/**
- * Build a media URL from a media reference ID.
- * If it's already an absolute URL, return as-is.
- */
-function buildMediaUrl(imageRef: string, siteUrl?: string): string {
-	// If already an absolute URL, return as-is
-	if (ABSOLUTE_URL_RE.test(imageRef)) {
-		return imageRef;
-	}
-
-	// Root-relative path — the CMS SEO panel stores seo_image as
-	// "/_emdash/api/media/file/01KS....svg" (already includes the API
-	// prefix). Without this branch we'd re-prefix and produce
-	// "${siteUrl}/_emdash/api/media/file//_emdash/api/media/file/<id>"
-	// which 404s and breaks <meta property="og:image">.
-	if (imageRef.startsWith("/")) {
-		return siteUrl ? `${siteUrl.replace(TRAILING_SLASH_RE, "")}${imageRef}` : imageRef;
-	}
-
-	// Bare media_id — build the full media API path
-	const mediaPath = `/_emdash/api/media/file/${imageRef}`;
-	if (siteUrl) {
-		return `${siteUrl.replace(TRAILING_SLASH_RE, "")}${mediaPath}`;
-	}
-	return mediaPath;
-}

package/src/seo/media-url.ts

@@ -0,0 +1,32 @@
+/**
+ * Resolve a stored SEO image reference to a URL.
+ *
+ * The CMS SEO panel stores `seo_image` in one of these shapes:
+ * - an absolute URL (`https://...`) — returned as-is;
+ * - a root-relative path that already includes the media API prefix
+ *   (`/_emdash/api/media/file/01KS....webp`) — prefixed with `siteUrl`;
+ * - a bare media id (`01KS...`) — expanded to the media API path, then
+ *   prefixed with `siteUrl`.
+ *
+ * Shared by the SEO meta builder (`og:image`) and the sitemap route
+ * (`<image:image>`) so both resolve image references identically.
+ */
+const TRAILING_SLASH_RE = /\/$/;
+const ABSOLUTE_URL_RE = /^https?:\/\//i;
+
+export function buildSeoImageUrl(imageRef: string, siteUrl?: string): string {
+	// Already absolute — use as-is.
+	if (ABSOLUTE_URL_RE.test(imageRef)) {
+		return imageRef;
+	}
+
+	// Root-relative path (already includes the media API prefix). Without
+	// this branch we'd re-prefix and produce a doubled path that 404s.
+	if (imageRef.startsWith("/")) {
+		return siteUrl ? `${siteUrl.replace(TRAILING_SLASH_RE, "")}${imageRef}` : imageRef;
+	}
+
+	// Bare media id — build the full media API path.
+	const mediaPath = `/_emdash/api/media/file/${imageRef}`;
+	return siteUrl ? `${siteUrl.replace(TRAILING_SLASH_RE, "")}${mediaPath}` : mediaPath;
+}

package/src/settings/index.ts

@@ -7,12 +7,19 @@
 
 import type { Kysely } from "kysely";
 
+import { after } from "../after.js";
 import { MediaRepository } from "../database/repositories/media.js";
 import { OptionsRepository } from "../database/repositories/options.js";
 import type { Database } from "../database/types.js";
 import { getDb } from "../loader.js";
 import { peekRequestCache, requestCached } from "../request-cache.js";
 import type { Storage } from "../storage/types.js";
+import {
+	createIsolateCache,
+	type IsolateCache,
+	invalidateIsolateCache,
+	isolateCachedAsync,
+} from "../utils/isolate-cache.js";
 import type { SiteSettings, SiteSettingKey, MediaReference, SeoSettings } from "./types.js";
 
 /** Prefix for site settings in the options table */
@@ -27,29 +34,22 @@ const SETTINGS_PREFIX = "site:";
  * once-per-isolate. Cross-isolate staleness is bounded by isolate lifetime
  * (workerd typically recycles within minutes); acceptable for chrome.
  *
- * Stored on globalThis with a Symbol.for key so Vite SSR chunk duplication
- * doesn't produce two independent caches (same pattern as request-context.ts).
- *
- * Invalidation: every `site:*` write bumps `version`. Reads compare the
- * cached promise's version against the current version and refetch on
- * mismatch. Caching the promise (not the resolved value) lets concurrent
- * cold-isolate readers share the in-flight query.
+ * Backed by isolate-cache.ts: concurrent cold-isolate reads coalesce onto one
+ * query via a reclaimable single-flight lock and the resolved *value* is
+ * cached — never a shared in-flight promise, so a cancelled request can't
+ * poison the isolate (see that file's header). Stored on globalThis with a
+ * Symbol.for key so Vite SSR chunk duplication doesn't produce two
+ * independent caches (same pattern as request-context.ts).
  */
-interface SiteSettingsHolder {
-	version: number;
-	cached: Promise<Partial<SiteSettings>> | null;
-	cachedVersion: number;
-}
-
 const SITE_SETTINGS_CACHE_KEY = Symbol.for("emdash:site-settings");
 const g = globalThis as Record<symbol, unknown>;
-const holder: SiteSettingsHolder =
+const settingsCache: IsolateCache<Partial<SiteSettings>> =
 	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis singleton pattern (see request-context.ts)
-	(g[SITE_SETTINGS_CACHE_KEY] as SiteSettingsHolder | undefined) ??
+	(g[SITE_SETTINGS_CACHE_KEY] as IsolateCache<Partial<SiteSettings>> | undefined) ??
 	(() => {
-		const h: SiteSettingsHolder = { version: 0, cached: null, cachedVersion: -1 };
-		g[SITE_SETTINGS_CACHE_KEY] = h;
-		return h;
+		const c = createIsolateCache<Partial<SiteSettings>>();
+		g[SITE_SETTINGS_CACHE_KEY] = c;
+		return c;
 	})();
 
 /**
@@ -60,9 +60,7 @@ const holder: SiteSettingsHolder =
  * own cached copy until they expire — staleness bounded by isolate lifetime.
  */
 export function invalidateSiteSettingsCache(): void {
-	holder.version++;
-	holder.cached = null;
-	holder.cachedVersion = -1;
+	invalidateIsolateCache(settingsCache);
 }
 
 /**
@@ -210,25 +208,19 @@ export async function getSiteSettingWithDb<K extends SiteSettingKey>(
  * ```
  */
 export function getSiteSettings(): Promise<Partial<SiteSettings>> {
-	return requestCached("siteSettings", () => {
-		const versionAtCall = holder.version;
-		if (holder.cached && holder.cachedVersion === versionAtCall) {
-			return holder.cached;
-		}
-		const fetchPromise = (async () => {
-			const db = await getDb();
-			return getSiteSettingsWithDb(db);
-		})().catch((error) => {
-			if (holder.cached === fetchPromise) {
-				holder.cached = null;
-				holder.cachedVersion = -1;
-			}
-			throw error;
-		});
-		holder.cached = fetchPromise;
-		holder.cachedVersion = versionAtCall;
-		return fetchPromise;
-	});
+	// requestCached dedupes within a single request; isolateCachedAsync
+	// coalesces across requests and caches the resolved value for the
+	// isolate's lifetime without ever sharing an awaitable promise.
+	return requestCached("siteSettings", () =>
+		isolateCachedAsync(
+			settingsCache,
+			async () => {
+				const db = await getDb();
+				return getSiteSettingsWithDb(db);
+			},
+			{ anchor: (promise) => after(() => promise), ownerTimeoutMs: 30_000 },
+		),
+	);
 }
 
 /**

package/src/taxonomies/index.ts

@@ -120,15 +120,10 @@ export async function getTaxonomyTerms(
 		if (locale !== undefined) termsQuery = termsQuery.where("locale", "=", locale);
 		const rows = await termsQuery.execute();
 
-		// Counts are keyed by translation_group (what the pivot stores).
-		const countsResult = await db
-			.selectFrom("content_taxonomies")
-			.select(["taxonomy_id"])
-			.select((eb) => eb.fn.count<number>("entry_id").as("count"))
-			.groupBy("taxonomy_id")
-			.execute();
-		const counts = new Map<string, number>();
-		for (const row of countsResult) counts.set(row.taxonomy_id, row.count);
+		// Counts are keyed by translation_group (what the pivot stores) and are
+		// locale-independent, so the aggregate is shared across every taxonomy
+		// rendered in this request (Categories + Tags widgets, etc.).
+		const counts = await getTaxonomyTermCounts();
 
 		const flatTerms: TaxonomyTermRow[] = rows.map((row) => ({
 			id: row.id,
@@ -148,6 +143,7 @@ export async function getTaxonomyTerms(
 			name: term.name,
 			slug: term.slug,
 			label: term.label,
+			description: term.data ? JSON.parse(term.data).description : undefined,
 			children: [],
 			count: counts.get(term.translation_group ?? term.id) ?? 0,
 			locale: term.locale,
@@ -156,6 +152,27 @@ export async function getTaxonomyTerms(
 	});
 }
 
+/**
+ * Per-translation-group usage counts across all taxonomies, in one aggregate
+ * scan of `content_taxonomies`. Counts are locale-independent (the pivot stores
+ * translation_group), so a single request-cached entry serves every taxonomy
+ * that renders during the request.
+ */
+function getTaxonomyTermCounts(): Promise<Map<string, number>> {
+	return requestCached("taxonomy-term-counts", async () => {
+		const db = await getDb();
+		const countsResult = await db
+			.selectFrom("content_taxonomies")
+			.select(["taxonomy_id"])
+			.select((eb) => eb.fn.count<number>("entry_id").as("count"))
+			.groupBy("taxonomy_id")
+			.execute();
+		const counts = new Map<string, number>();
+		for (const row of countsResult) counts.set(row.taxonomy_id, row.count);
+		return counts;
+	});
+}
+
 /**
  * Get a single term by (taxonomy, slug). Honours the fallback chain — if the
  * slug exists in a fallback locale, we return that row (useful for deep-linking
@@ -289,10 +306,57 @@ export async function getTermsForEntries(
 	for (const id of uniqueIds) result.set(id, []);
 	if (uniqueIds.length === 0) return result;
 
-	const db = await getDb();
 	const locale = resolveLocale(options.locale);
+	const localeKey = locale ?? "*";
 
-	for (const chunk of chunks(uniqueIds, SQL_BATCH_SIZE)) {
+	// Entry-term hydration (getAllTermsForEntries -> primeEntryTermsCache)
+	// seeds the per-entry cache under the same key getEntryTerms uses:
+	// `terms:${collection}:${entryId}:${taxonomyName}:${localeKey}`, storing a
+	// TaxonomyTerm[] (including `[]` for entries with no terms). Satisfy those
+	// from cache and run the batched query only for the ids that missed.
+	const missedIds: string[] = [];
+	type CacheRead = { id: string; terms: TaxonomyTerm[] } | { id: string; miss: true };
+	const cacheReads: Array<Promise<CacheRead>> = [];
+	for (const id of uniqueIds) {
+		const cached = peekRequestCache<TaxonomyTerm[]>(
+			`terms:${collection}:${id}:${taxonomyName}:${localeKey}`,
+		);
+		if (cached) {
+			// A peeked promise can reject (e.g. a sibling getEntryTerms hit a
+			// missing table). Treat a rejection as a cache miss so the batched
+			// query path -- and its isMissingTableError guard below -- still runs,
+			// rather than propagating an uncaught error.
+			cacheReads.push(
+				cached.then(
+					(terms): CacheRead => ({ id, terms }),
+					(): CacheRead => ({ id, miss: true }),
+				),
+			);
+		} else {
+			missedIds.push(id);
+		}
+	}
+	for (const read of await Promise.all(cacheReads)) {
+		if ("miss" in read) {
+			missedIds.push(read.id);
+			continue;
+		}
+		// Return a private copy. The cached array and its term objects are shared
+		// with getEntryTerms/getAllTermsForEntries (primeEntryTermsCache stores
+		// the same references), so a caller that mutates the result -- sorting in
+		// place, pushing into `children` -- must not poison the cache. The
+		// pre-cache implementation always returned freshly built arrays.
+		result.set(
+			read.id,
+			read.terms.map((t) => ({ ...t, children: [...t.children] })),
+		);
+	}
+
+	if (missedIds.length === 0) return result;
+
+	const db = await getDb();
+
+	for (const chunk of chunks(missedIds, SQL_BATCH_SIZE)) {
 		let rows;
 		try {
 			let query = db
@@ -310,7 +374,10 @@ export async function getTermsForEntries(
 				])
 				.where("content_taxonomies.collection", "=", collection)
 				.where("content_taxonomies.entry_id", "in", chunk)
-				.where("taxonomies.name", "=", taxonomyName);
+				.where("taxonomies.name", "=", taxonomyName)
+				// Match the order getAllTermsForEntries (the cache primer) uses, so
+				// cache-hit and DB-miss entries in one result are ordered consistently.
+				.orderBy("taxonomies.label", "asc");
 			if (locale !== undefined) query = query.where("taxonomies.locale", "=", locale);
 			rows = await query.execute();
 		} catch (error) {

package/src/utils/isolate-cache.ts

@@ -0,0 +1,189 @@
+/**
+ * Isolate-lifetime async value cache with single-flight and poison-immunity.
+ *
+ * Built for the "compute once per isolate, read on every request" caches
+ * (site settings, search-health verification, ...). These must coalesce
+ * concurrent cold-isolate reads into one query — but the obvious way to do
+ * that, caching the in-flight *promise* on an isolate-global and awaiting it
+ * from later requests, is unsafe on workerd: if the request that created the
+ * promise is cancelled mid-await (client disconnect, context teardown), its
+ * continuation never runs, so the promise neither resolves nor rejects. Every
+ * later request that awaits that shared promise then hangs until the isolate
+ * is evicted (observed as 524s at the 100s wall, near-zero CPU). A `.catch`
+ * that clears the cache doesn't help — a cancelled request doesn't reject.
+ *
+ * This cache stores the resolved *value* (not a promise) and coalesces via
+ * `initWithLock`: one request becomes the owner and runs `fetch`, everyone
+ * else polls for the published value and never awaits the owner's promise.
+ * A cancelled owner can therefore never strand a waiter — the worst case is
+ * the lock looks held until `deadlineMs`, then the next caller reclaims. The
+ * owner's `fetch` is also anchored (waitUntil) so a cancelled originator's
+ * query still completes and populates the cache, and bounded by
+ * `ownerTimeoutMs` so a genuinely stuck fetch reclaims instead of hanging.
+ *
+ * Invalidation bumps `version`; reads compare against the version captured at
+ * call time and refetch on mismatch.
+ */
+
+import { createInitLock, type InitLock, initWithLock } from "./init-lock.js";
+
+export interface IsolateCache<T> {
+	/** Last resolved value, valid only when `hasValue` is true. */
+	value: T | null;
+	/**
+	 * Presence flag, separate from `value` so that falsy/`undefined`/`void`
+	 * results cache correctly (a plain null check can't distinguish "cached
+	 * undefined" from "never fetched").
+	 */
+	hasValue: boolean;
+	/** Invalidation counter; bumped by `invalidateIsolateCache`. */
+	version: number;
+	/** The `version` the cached value was fetched at. */
+	valueVersion: number;
+	/** Reclaimable single-flight lock (see init-lock.ts). */
+	lock: InitLock;
+}
+
+export function createIsolateCache<T>(): IsolateCache<T> {
+	return { value: null, hasValue: false, version: 0, valueVersion: -1, lock: createInitLock() };
+}
+
+/**
+ * Force the next `isolateCachedAsync` call to refetch. An in-flight owner
+ * fetched at the old version will not publish into the new version, so its
+ * result is ignored by subsequent reads.
+ */
+export function invalidateIsolateCache(cache: IsolateCache<unknown>): void {
+	cache.version++;
+	cache.hasValue = false;
+	cache.value = null;
+	cache.valueVersion = -1;
+	// Free the single-flight lock so a reader at the new version starts the
+	// refetch immediately instead of waiting out a stale owner's deadline. A
+	// still-running old-version owner can neither publish into the new version
+	// (version gate) nor clobber a new owner (claim gate), so releasing here
+	// is safe; the worst case is one brief duplicate fetch.
+	cache.lock.ownerStartedAt = null;
+}
+
+/**
+ * Headroom between the owner's own timeout and the waiter reclaim deadline.
+ * The reclaim deadline must sit *above* `ownerTimeoutMs` so a slow-but-live
+ * owner times out (and releases the lock) before a waiter would reclaim it —
+ * otherwise a fetch slower than the deadline is superseded before it can
+ * publish, and steady traffic turns that into a self-sustaining stampede.
+ */
+const RECLAIM_HEADROOM_MS = 5_000;
+
+export interface IsolateCachedOptions {
+	/**
+	 * Hand the in-flight fetch to the host's lifetime extender (waitUntil via
+	 * `after()`), so a cancelled originating request still drives it to
+	 * completion and populates the cache.
+	 */
+	anchor?: (promise: Promise<void>) => void;
+	/** Reclaim the single-flight lock if the owner holds it past this. */
+	deadlineMs?: number;
+	/** Waiter poll interval. */
+	pollMs?: number;
+	/** Waiter gives up and throws after this long rather than hanging. */
+	maxWaitMs?: number;
+	/**
+	 * Bound the owner's own `fetch`: if it doesn't settle within this, the
+	 * owner rejects (and releases the lock) instead of waiting indefinitely.
+	 * The anchored copy keeps running, so a slow-but-live fetch can still
+	 * publish for a later caller. Omit to leave the owner unbounded.
+	 */
+	ownerTimeoutMs?: number;
+}
+
+/** Boxed cache hit so a `void`/falsy value is still distinguishable from a miss. */
+interface Box<T> {
+	v: T;
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const timer = setTimeout(() => {
+			reject(new Error(`isolateCachedAsync: owner fetch exceeded ${ms}ms`));
+		}, ms);
+		// Settle from the underlying promise (whichever wins the race with the
+		// timer), and always clear the timer so a resolved fetch doesn't leave
+		// a pending timeout holding the isolate alive.
+		promise.then(resolve, reject).finally(() => {
+			clearTimeout(timer);
+		});
+	});
+}
+
+/**
+ * Return the cached value for `cache`, computing it via `fetch` under a
+ * single-flight lock on a miss. Concurrent callers coalesce onto one fetch;
+ * a cancelled owner cannot poison later callers (see file header).
+ */
+export function isolateCachedAsync<T>(
+	cache: IsolateCache<T>,
+	fetch: () => Promise<T>,
+	options: IsolateCachedOptions = {},
+): Promise<T> {
+	// Capture the version once: a value published at this version satisfies
+	// this call; an invalidation that lands mid-fetch makes the published
+	// value stale for *later* calls (which captured the newer version) but
+	// still valid for this one.
+	const versionAtCall = cache.version;
+
+	// Ignore a non-positive / non-finite owner timeout rather than letting it
+	// degenerate into an instant-reject (setTimeout coerces NaN/0 to ~0ms).
+	const ownerTimeoutMs =
+		options.ownerTimeoutMs !== undefined &&
+		Number.isFinite(options.ownerTimeoutMs) &&
+		options.ownerTimeoutMs > 0
+			? options.ownerTimeoutMs
+			: undefined;
+
+	// Keep the reclaim deadline above the owner timeout (see RECLAIM_HEADROOM_MS):
+	// the owner's own timeout, not a waiter reclaim, is the primary release.
+	const deadlineMs =
+		ownerTimeoutMs === undefined
+			? options.deadlineMs
+			: Math.max(options.deadlineMs ?? 0, ownerTimeoutMs + RECLAIM_HEADROOM_MS);
+
+	return initWithLock<Box<T>>(
+		cache.lock,
+		() =>
+			cache.hasValue && cache.valueVersion === versionAtCall
+				? // eslint-disable-next-line typescript/no-unsafe-type-assertion -- hasValue gates that `value` holds a real T
+					({ v: cache.value as T } satisfies Box<T>)
+				: null,
+		(isCurrentClaim) => {
+			// The real work, anchored independently so a cancelled owner's
+			// fetch still settles and publishes. Publication is gated on the
+			// claim so a reclaimed slow owner can't clobber the reclaimer's
+			// value (same contract as initWithLock's own callers).
+			const real = (async (): Promise<Box<T>> => {
+				const value = await fetch();
+				if (isCurrentClaim()) {
+					cache.value = value;
+					cache.hasValue = true;
+					cache.valueVersion = versionAtCall;
+				}
+				return { v: value };
+			})();
+			// Anchor the real fetch (not the timeout race): this is what must
+			// survive a cancelled owner and run to publication. initWithLock is
+			// left to manage only the lock; we don't double-anchor.
+			options.anchor?.(
+				real.then(
+					() => undefined,
+					() => undefined,
+				),
+			);
+			return ownerTimeoutMs === undefined ? real : withTimeout(real, ownerTimeoutMs);
+		},
+		{
+			deadlineMs,
+			pollMs: options.pollMs,
+			maxWaitMs: options.maxWaitMs,
+		},
+	).then((box) => box.v);
+}

package/src/virtual-modules.d.ts

@@ -132,6 +132,17 @@ declare module "virtual:emdash/wait-until" {
 	export const waitUntil: ((promise: Promise<unknown>) => void) | undefined;
 }
 
+declare module "virtual:emdash/scheduler" {
+	import type { CreateSchedulerFn } from "./emdash-runtime.js";
+	/**
+	 * Factory for the timer-based cron/maintenance heartbeat. A
+	 * `NodeCronScheduler` factory on long-lived runtimes (Node/Bun); `null`
+	 * under serverless adapters (e.g. Cloudflare) where an external Cron
+	 * Trigger drives scheduled work instead.
+	 */
+	export const createScheduler: CreateSchedulerFn | null;
+}
+
 declare module "virtual:emdash/admin-registry" {
 	/**
 	 * Plugin admin module registry.