emdash 0.32.0 → 0.34.0

package/src/database/repositories/types.ts

@@ -1,3 +1,4 @@
+import type { ContentFieldFilters } from "../../content-list-query.js";
 import type { CustomFieldValue } from "../../schema/types.js";
 import { encodeBase64, decodeBase64 } from "../../utils/base64.js";
 
@@ -12,6 +13,8 @@ import { encodeBase64, decodeBase64 } from "../../utils/base64.js";
 const MAX_CURSOR_LENGTH = 4096;
 
 export interface CreateContentInput {
+	/** Explicit content ID for stable seed imports. Omit to generate a ULID. */
+	id?: string;
 	type: string;
 	slug?: string | null;
 	data: Record<string, unknown>;
@@ -145,6 +148,34 @@ export interface ContentDateFilter {
 	to?: string;
 }
 
+/**
+ * Byline filter for a content list.
+ *
+ * `mode: "any"` matches entries credited to at least one of `bylineIds`;
+ * `mode: "none"` matches entries with no credit at all.
+ *
+ * `bylineIds` are `translation_group` values — what
+ * `_emdash_content_bylines.byline_id` stores since migration 040 — so a filter
+ * matches a byline across every locale variant.
+ *
+ * By default only explicit credits count. `includeInferred` widens the filter
+ * to the byline the list actually renders, which for an entry with no credits
+ * is the one linked to its `author_id` (see `hydrateBylinesMany`).
+ */
+export interface ContentBylineFilter {
+	mode: "any" | "none";
+	/** Ignored when `mode` is `"none"`. An empty list matches nothing. */
+	bylineIds?: string[];
+	includeInferred?: boolean;
+	/**
+	 * Locale a credit has to resolve at — the locale the list is scoped to.
+	 * Applies to explicit credits as well as inferred ones, since a byline
+	 * group credited to an entry renders only where it has a row at that
+	 * locale. Defaults to each entry's own locale when the list spans locales.
+	 */
+	locale?: string;
+}
+
 export interface FindManyOptions {
 	where?: {
 		status?: string;
@@ -154,8 +185,9 @@ export interface FindManyOptions {
 		q?: string;
 		/**
 		 * Columns the `q` substring filter is applied to (OR'd together).
-		 * Resolved by the handler from the collection's display fields so the
-		 * repository stays generic. Each name is validated as a SQL identifier.
+		 * Resolved by the handler from the collection's display fields, slug,
+		 * and any field marked searchable. Each name is validated as a SQL
+		 * identifier.
 		 */
 		searchColumns?: string[];
 		/**
@@ -168,11 +200,21 @@ export interface FindManyOptions {
 		useFts?: boolean;
 		/** Inclusive date range over a whitelisted timestamp column. */
 		dateFilter?: ContentDateFilter;
+		/** Restrict to entries by their byline credits. */
+		bylineFilter?: ContentBylineFilter;
+		/** AND-combined filters over custom fields explicitly marked as indexed. */
+		fieldFilters?: ContentFieldFilters;
 	};
 	orderBy?: {
 		field: string;
 		direction: "asc" | "desc";
 	};
+	/**
+	 * Extra field slugs allowed as `orderBy` beyond the system columns — the
+	 * collection's configured titleField/dateField. Resolved by the
+	 * handler server-side so `orderBy` stays a closed set per request.
+	 */
+	sortableExtras?: string[];
 	limit?: number;
 	cursor?: string; // Base64-encoded JSON: {orderValue: string, id: string}
 }
@@ -278,6 +320,13 @@ export class EmDashValidationError extends Error {
 	}
 }
 
+export class ContentCollectionNotFoundError extends Error {
+	constructor(collection: string) {
+		super(`Collection '${collection}' not found`);
+		this.name = "ContentCollectionNotFoundError";
+	}
+}
+
 /**
  * Thrown by `publish()` when called with `requireDue` for a row that is no
  * longer due (its `scheduled_at` was cleared or pushed into the future between
@@ -290,3 +339,10 @@ export class ScheduledNotDueError extends Error {
 		this.name = "ScheduledNotDueError";
 	}
 }
+
+export class ContentMutationConflictError extends Error {
+	constructor(message = "Content changed while the operation was in progress") {
+		super(message);
+		this.name = "ContentMutationConflictError";
+	}
+}

package/src/database/types.ts

@@ -13,6 +13,12 @@ export interface RevisionTable {
 	created_at: Generated<string>;
 }
 
+export interface RevisionPruneQueueTable {
+	collection: string;
+	entry_id: string;
+	revision_id: string;
+}
+
 export interface TaxonomyTable {
 	id: string;
 	name: string;
@@ -22,27 +28,18 @@ export interface TaxonomyTable {
 	data: string | null; // JSON
 	locale: Generated<string>; // e.g. 'en', 'es', 'fr'
 	translation_group: string | null; // shared across translations of the same term
+	// Manual order within a sibling group. 0 for terms that were never
+	// explicitly reordered, so listings fall back to alphabetical.
+	sort_order: Generated<number>;
 }
 
 export interface ContentTaxonomyTable {
 	collection: string; // e.g., 'posts'
-	entry_id: string; // ID in the ec_* table
+	entry_id: string; // stores the ec_* row's translation_group (locale-agnostic)
 	taxonomy_id: string; // stores taxonomies.translation_group (locale-agnostic)
-	// Denormalized filter + sort columns mirrored from the entry's ec_* row
-	// (migration 051). They let a taxonomy-filtered listing seek the matching
-	// entries directly on the pivot instead of scanning the whole collection.
-	//
-	// ADVISORY, not authoritative: D1 has no transactions, so the write-path
-	// re-stamp (ContentRepository / TaxonomyRepository) is a separate statement
-	// from the ec_* mutation and can be transiently stale. The read path narrows
-	// the candidate set with these columns but re-checks the real filter
-	// predicates on the joined ec_* row. `updated_at` is deliberately NOT
-	// denormalized — it moves on every edit, so denormalizing it would force a
-	// pivot re-stamp on the common edit path for little read value.
-	//
-	// Nullable/Generated so inserts that predate a re-stamp (or the migration
-	// backfill) leave them NULL; every insert site in the repositories stamps
-	// them explicitly.
+	// Legacy denormalized columns from migration 051. A group assignment spans
+	// locale rows whose status and dates may differ, so current reads use the
+	// authoritative ec_* rows and new pivot inserts leave these nullable.
 	status: Generated<string | null>;
 	scheduled_at: Generated<string | null>;
 	deleted_at: Generated<string | null>;
@@ -93,6 +90,7 @@ export interface MediaUploadAttemptTable {
 export interface MediaUsageSourceTable {
 	source_key: string;
 	source_type: string;
+	collection_id: Generated<string | null>;
 	collection_slug: string | null;
 	content_id: string | null;
 	source_variant: string;
@@ -109,6 +107,7 @@ export interface MediaUsageSourceTable {
 	source_updated_at: Generated<string | null>;
 	source_version: Generated<number | null>;
 	source_fingerprint: Generated<string | null>;
+	identity_version: Generated<number | null>;
 	source_completeness: Generated<string>;
 	last_attempted_at: Generated<string | null>;
 	last_error_code: Generated<string | null>;
@@ -131,6 +130,44 @@ export interface MediaUsageTable {
 	media_kind: string | null;
 	mime_type: string | null;
 	created_at: Generated<string>;
+	cleanup_lease_token: Generated<string | null>;
+}
+
+export interface MediaUsageCleanupTable {
+	task_key: string;
+	lease_token: string | null;
+	lease_expires_at: string | null;
+	next_eligible_at: string;
+	cursor_created_at: string | null;
+	cursor_id: string | null;
+	scan_before_at: string | null;
+	consecutive_failures: Generated<number>;
+	last_started_at: string | null;
+	last_completed_at: string | null;
+	last_candidate_count: Generated<number>;
+	last_deleted_orphans: Generated<number>;
+	last_deleted_stale: Generated<number>;
+	last_deleted_abandoned: Generated<number>;
+	last_deleted_write_leases: Generated<number>;
+	last_backlog_lower_bound: Generated<number>;
+	last_scan_has_more: Generated<number>;
+	last_duration_ms: Generated<number>;
+	last_error_code: string | null;
+	updated_at: Generated<string>;
+}
+
+export interface MediaUsageGenerationWriteTable {
+	source_key: string;
+	generation: string;
+	lease_token: string;
+	expires_at: string;
+	created_at: Generated<string>;
+}
+
+export interface MediaUsageGenerationFenceTable {
+	task_key: string;
+	generation_floor: string;
+	updated_at: Generated<string>;
 }
 
 export interface MediaUsageIndexStatusTable {
@@ -146,6 +183,84 @@ export interface MediaUsageIndexStatusTable {
 	failed_source_count: Generated<number>;
 	last_error_code: Generated<string | null>;
 	updated_at: Generated<string>;
+	collection_id: Generated<string | null>;
+	change_epoch: Generated<number | string>;
+	reconciliation_required: Generated<number>;
+	last_incremental_success_at: Generated<string | null>;
+	capture_state: Generated<string | null>;
+}
+
+export interface MediaUsageActivationTable {
+	task_key: string;
+	state: Generated<string>;
+	runtime_generation: Generated<number>;
+	collection_cursor: Generated<string | null>;
+	drain_confirmed_at: Generated<string | null>;
+	lease_token: Generated<string | null>;
+	lease_expires_at: Generated<string | null>;
+	attempt_count: Generated<number>;
+	last_attempted_at: Generated<string | null>;
+	last_error_code: Generated<string | null>;
+	activated_at: Generated<string | null>;
+	created_at: Generated<string>;
+	updated_at: Generated<string>;
+	media_usage_maintenance_turn: Generated<number>;
+}
+
+export interface MediaUsageWorkTable {
+	collection_id: string;
+	collection_slug: string;
+	content_id: string;
+	change_epoch: number | string;
+	work_version: Generated<number | string>;
+	state: Generated<string>;
+	attempt_count: Generated<number>;
+	next_attempt_at: string;
+	lease_token: Generated<string | null>;
+	lease_expires_at: Generated<string | null>;
+	last_attempted_at: Generated<string | null>;
+	last_error_code: Generated<string | null>;
+	created_at: Generated<string>;
+	updated_at: Generated<string>;
+}
+
+export interface MediaUsageCollectionDeletionTable {
+	collection_id: string;
+	collection_slug: string;
+	force_delete: number;
+	state: Generated<string>;
+	phase: Generated<string>;
+	work_cursor: Generated<string | null>;
+	source_key: Generated<string | null>;
+	occurrence_cursor: Generated<string | null>;
+	attempt_count: Generated<number>;
+	next_attempt_at: string;
+	lease_token: Generated<string | null>;
+	lease_expires_at: Generated<string | null>;
+	last_error_code: Generated<string | null>;
+	created_at: Generated<string>;
+	updated_at: Generated<string>;
+}
+
+export interface MediaUsageReconciliationTable {
+	collection_id: string;
+	collection_slug: string;
+	run_token: string;
+	target_epoch: Generated<number | string | null>;
+	field_fingerprint: Generated<string | null>;
+	state: Generated<string>;
+	phase: Generated<string>;
+	scan_cursor: Generated<string | null>;
+	scan_upper_id: Generated<string | null>;
+	source_cursor: Generated<string | null>;
+	source_upper_key: Generated<string | null>;
+	attempt_count: Generated<number>;
+	next_attempt_at: string;
+	lease_token: Generated<string | null>;
+	lease_expires_at: Generated<string | null>;
+	last_error_code: Generated<string | null>;
+	created_at: Generated<string>;
+	updated_at: Generated<string>;
 }
 
 export interface UserTable {
@@ -300,11 +415,17 @@ export interface CollectionTable {
 	label_singular: string | null;
 	description: string | null;
 	icon: string | null;
+	admin_config: Generated<string | null>; // JSON: { listColumns?: string[] }
 	supports: string | null; // JSON array
 	source: string | null;
-	search_config: string | null; // JSON: { enabled: boolean, weights: Record<string, number> }
+	search_config: string | null; // JSON: SearchConfig
 	has_seo: number; // 0 or 1 — opt-in SEO fields for this collection
+	title_field: string | null; // field slug for the admin list Title column (NULL = default)
+	date_field: string | null; // field slug (datetime) for the admin list Date column (NULL = default)
 	url_pattern: string | null; // URL pattern with {slug} placeholder (e.g. "/blog/{slug}")
+	routable: Generated<number>; // 0 or 1 — published entries require a slug when enabled
+	hidden: Generated<number>; // 0 or 1 — omit the auto-generated admin sidebar entry
+	sort_order: number | null; // explicit admin sidebar position; NULL = alphabetical fallback
 	comments_enabled: Generated<number>; // 0 or 1
 	comments_moderation: Generated<string>; // 'all' | 'first_time' | 'none'
 	comments_closed_after_days: Generated<number>; // 0 = never close
@@ -340,6 +461,7 @@ export interface FieldTable {
 	options: string | null; // JSON
 	sort_order: number;
 	searchable: Generated<number>; // boolean as 0/1, defaults to 0
+	indexed: Generated<number>; // boolean as 0/1, defaults to 0
 	translatable: Generated<number>; // boolean as 0/1, defaults to 1
 	created_at: Generated<string>;
 }
@@ -500,6 +622,7 @@ export interface SectionTable {
 // Note: ec_* content tables are dynamic and not part of this type
 export interface Database {
 	revisions: RevisionTable;
+	_emdash_revision_prune_queue: RevisionPruneQueueTable;
 	taxonomies: TaxonomyTable;
 	content_taxonomies: ContentTaxonomyTable;
 	_emdash_taxonomy_defs: TaxonomyDefTable;
@@ -507,7 +630,14 @@ export interface Database {
 	_emdash_media_upload_attempts: MediaUploadAttemptTable;
 	_emdash_media_usage_sources: MediaUsageSourceTable;
 	_emdash_media_usage: MediaUsageTable;
+	_emdash_media_usage_cleanup: MediaUsageCleanupTable;
+	_emdash_media_usage_generation_writes: MediaUsageGenerationWriteTable;
+	_emdash_media_usage_cleanup_fence: MediaUsageGenerationFenceTable;
 	_emdash_media_usage_index_status: MediaUsageIndexStatusTable;
+	_emdash_media_usage_activation: MediaUsageActivationTable;
+	_emdash_media_usage_work: MediaUsageWorkTable;
+	_emdash_media_usage_collection_deletions: MediaUsageCollectionDeletionTable;
+	_emdash_media_usage_reconciliations: MediaUsageReconciliationTable;
 	users: UserTable;
 	credentials: CredentialTable;
 	auth_tokens: AuthTokenTable;

package/src/database/validate.ts

@@ -26,6 +26,13 @@ const GENERIC_IDENTIFIER_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
  */
 const PLUGIN_IDENTIFIER_PATTERN = /^[a-z][a-z0-9_-]*$/;
 
+/**
+ * Pattern for plugin storage collection names.
+ * Manifests declare these as free-form keys, so both cases and hyphens are
+ * allowed; the charset still excludes quotes, whitespace, and punctuation.
+ */
+const STORAGE_COLLECTION_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+
 /**
  * Maximum length for SQL identifiers.
  * SQLite has no formal limit, but we cap at 128 for sanity.
@@ -136,3 +143,35 @@ export function validatePluginIdentifier(value: string, label = "plugin identifi
 		throw new IdentifierError(`${label} must match /^[a-z][a-z0-9_-]*$/ (got "${value}")`, value);
 	}
 }
+
+/**
+ * Validate a plugin storage collection name.
+ *
+ * Collections are declared as free-form manifest keys and stored as opaque
+ * text, so this is deliberately more permissive than `validateIdentifier`:
+ * `form-submissions` and `formSubmissions` are legitimate. The charset still
+ * rejects quotes and punctuation, keeping generated index names inert.
+ *
+ * @param value - The string to validate
+ * @param label - Human-readable label for error messages
+ * @throws {IdentifierError} If the value is not valid
+ */
+export function validateStorageCollectionName(value: string, label = "collection name"): void {
+	if (!value || typeof value !== "string") {
+		throw new IdentifierError(`${label} must be a non-empty string`, String(value));
+	}
+
+	if (value.length > MAX_IDENTIFIER_LENGTH) {
+		throw new IdentifierError(
+			`${label} must be ${MAX_IDENTIFIER_LENGTH} characters or less, got ${value.length}`,
+			value,
+		);
+	}
+
+	if (!STORAGE_COLLECTION_PATTERN.test(value)) {
+		throw new IdentifierError(
+			`${label} must match /^[a-zA-Z][a-zA-Z0-9_-]*$/ (got "${value}")`,
+			value,
+		);
+	}
+}

package/src/db/adapters.ts

@@ -26,6 +26,32 @@
  */
 export type DatabaseDialectType = "sqlite" | "postgres";
 
+export type CollectionDeletionGuardInput =
+	| {
+			action: "fence";
+			collectionId: string;
+			collectionSlug: string;
+			leaseToken: string;
+			forceDelete: boolean;
+	  }
+	| {
+			action: "drop";
+			collectionId: string;
+			collectionSlug: string;
+			leaseToken: string;
+	  };
+
+export type CollectionDeletionGuardResult =
+	| { outcome: "fenced" }
+	| { outcome: "has_content" }
+	| { outcome: "stale" }
+	| { outcome: "dropped" };
+
+export type ExecuteCollectionDeletionGuard = (
+	config: unknown,
+	input: CollectionDeletionGuardInput,
+) => Promise<CollectionDeletionGuardResult>;
+
 /**
  * Database descriptor - serializable config for virtual modules
  */
@@ -48,6 +74,14 @@ export interface DatabaseDescriptor {
 	 * the middleware takes its default (singleton) path.
 	 */
 	supportsRequestScope?: boolean;
+	/**
+	 * When true, request middleware resolves the last content-namespace
+	 * invalidation timestamp and passes it to `createRequestScopedDb`.
+	 *
+	 * Keep this unset unless request routing depends on that timestamp: reading
+	 * it may require an object-cache backend round trip.
+	 */
+	needsLastContentWriteAt?: boolean;
 	/**
 	 * When true, the adapter's runtime entrypoint MUST export a named
 	 * `createCoalescingDialect` function. The runtime uses this fresh dialect
@@ -57,6 +91,8 @@ export interface DatabaseDescriptor {
 	 * inspecting an optional entrypoint export.
 	 */
 	supportsCoalescing?: boolean;
+	/** The runtime entrypoint exports the deletion-specific atomic guard. */
+	supportsCollectionDeletionGuard?: boolean;
 }
 
 export interface SqliteConfig {

package/src/db/index.ts

@@ -26,6 +26,9 @@ export type {
 	SqliteConfig,
 	LibsqlConfig,
 	PostgresConfig,
+	CollectionDeletionGuardInput,
+	CollectionDeletionGuardResult,
+	ExecuteCollectionDeletionGuard,
 } from "./adapters.js";
 
 // Migration utilities (used by playground, preview, and custom deployment scripts)

package/src/deferred-tasks.ts

@@ -0,0 +1,71 @@
+export interface DeferredTaskTracker {
+	settled: Promise<void>;
+	track<T>(promise: Promise<T>): Promise<T>;
+	settle(): void;
+}
+
+// Test database teardown uses this process-local registry to drain tasks that
+// run without request middleware. Keep it on globalThis so duplicated SSR
+// chunks and their test helpers observe the same task set.
+const DEFERRED_TASKS_KEY = Symbol.for("emdash:deferred-tasks");
+
+const deferredTasks: Set<Promise<unknown>> =
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis singleton pattern
+	((globalThis as Record<symbol, unknown>)[DEFERRED_TASKS_KEY] as
+		| Set<Promise<unknown>>
+		| undefined) ??
+	(() => {
+		const tasks = new Set<Promise<unknown>>();
+		(globalThis as Record<symbol, unknown>)[DEFERRED_TASKS_KEY] = tasks;
+		return tasks;
+	})();
+
+export function trackDeferredTask<T>(promise: Promise<T>): Promise<T> {
+	let tracked!: Promise<T>;
+	tracked = promise.finally(() => deferredTasks.delete(tracked));
+	deferredTasks.add(tracked);
+	return tracked;
+}
+
+export async function waitForDeferredTasks(): Promise<void> {
+	while (deferredTasks.size > 0) {
+		await Promise.allSettled(deferredTasks);
+	}
+}
+
+export function createDeferredTaskTracker(onSettled: () => void): DeferredTaskTracker {
+	let pending = 0;
+	let responseSettled = false;
+	let completed = false;
+	let resolveSettled!: () => void;
+	const settled = new Promise<void>((resolve) => {
+		resolveSettled = resolve;
+	});
+
+	const completeIfSettled = () => {
+		if (completed || !responseSettled || pending > 0) return;
+		completed = true;
+		try {
+			onSettled();
+		} finally {
+			resolveSettled();
+		}
+	};
+
+	return {
+		settled,
+		track<T>(promise: Promise<T>): Promise<T> {
+			pending++;
+			return promise.finally(() => {
+				// A task may register another after() call before it settles. The
+				// counter therefore reaches zero only after the full task chain ends.
+				pending--;
+				completeIfSettled();
+			});
+		},
+		settle(): void {
+			responseSettled = true;
+			completeIfSettled();
+		},
+	};
+}