@growth-labs/cms 0.1.2 → 0.2.0

package/src/engine/publication.ts

@@ -0,0 +1,2152 @@
+import type {
+	ContentPublicationAttemptRow,
+	ContentPublicationAttemptState,
+	ContentType,
+} from '../schema/types.js'
+import type { D1Database, D1Result } from './d1.js'
+import { evaluateArticleBody } from './publish-guard.js'
+import {
+	type CreateContentInput,
+	createContent,
+	ensureUniqueSlug,
+	getContentItem,
+	getContentSnapshot,
+	PublishContentValidationError,
+} from './publisher.js'
+import { getRevision } from './revisions.js'
+import { slugify } from './slug.js'
+
+export type PublicationOperation = 'publish' | 'rollback'
+export type PublicationSurfacePhase = 'prepare' | 'commit' | 'abort'
+export type PublicationSurfaceStatus = 'ok' | 'skipped' | 'failed'
+export type PublicationSurfaceCommitStatus = 'none' | 'committed' | 'pending_retry'
+
+export interface PublicationSurfaceReceipt {
+	name: string
+	status: PublicationSurfaceStatus
+	phase?: PublicationSurfacePhase
+	message?: string
+	durationMs?: number
+}
+
+export interface PublicationReconciliationInput {
+	operation: PublicationOperation
+	contentId: string
+	revisionId: string
+	previousRevisionId: string | null
+	snapshot: Record<string, unknown>
+	now: number
+	packageVersion?: string | null
+	phase?: PublicationSurfacePhase
+	/** Aborted when the bounded surface-hook deadline expires. */
+	signal?: AbortSignal
+}
+
+export interface PublicationReconciler {
+	name: string
+	/**
+	 * Prepare revision-addressed, non-public artifacts. This phase runs before the
+	 * canonical pointer CAS, must be idempotent, and must not expose the target
+	 * revision to readers.
+	 */
+	prepare?(input: PublicationReconciliationInput): Promise<PublicationSurfaceReceipt | undefined>
+	/**
+	 * Commit live surfaces after the canonical pointer moved. Implementations must
+	 * be idempotent because a Worker can crash after the external commit but before
+	 * its durable receipt is recorded.
+	 */
+	commit?(input: PublicationReconciliationInput): Promise<PublicationSurfaceReceipt | undefined>
+	/** Abort prepared or committed artifacts after a failed prepare/CAS path. */
+	abort?(input: PublicationReconciliationInput): Promise<PublicationSurfaceReceipt | undefined>
+	/** @deprecated Unsupported by the durable publication contract; use commit. */
+	reconcile?(input: PublicationReconciliationInput): Promise<PublicationSurfaceReceipt | undefined>
+}
+
+export interface PublishOneInput {
+	contentId: string
+	now?: number
+	createdBy?: string | null
+	surfaces?: PublicationReconciler[]
+	allowNoSurfaces?: boolean
+	requiredSurfaceNames?: string[]
+	packageVersion?: string | null
+	surfaceHookTimeoutMs?: number
+}
+
+export interface PublishOneReceipt {
+	status: 'published'
+	attemptId: string
+	contentId: string
+	revisionId: string
+	previousRevisionId: string | null
+	publishedAt: number
+	surfaceStatus: PublicationSurfaceCommitStatus
+	surfaces: PublicationSurfaceReceipt[]
+	packageVersion: string | null
+}
+
+export interface RollbackPublicationInput {
+	contentId: string
+	targetRevisionId: string
+	now?: number
+	surfaces?: PublicationReconciler[]
+	allowNoSurfaces?: boolean
+	requiredSurfaceNames?: string[]
+	packageVersion?: string | null
+	surfaceHookTimeoutMs?: number
+}
+
+export interface RollbackPublicationReceipt {
+	status: 'rolled_back'
+	attemptId: string
+	contentId: string
+	revisionId: string
+	previousRevisionId: string | null
+	rolledBackAt: number
+	surfaceStatus: PublicationSurfaceCommitStatus
+	surfaces: PublicationSurfaceReceipt[]
+	packageVersion: string | null
+}
+
+export interface RetryPublicationSurfacesInput {
+	attemptId: string
+	now?: number
+	surfaces?: PublicationReconciler[]
+	surfaceHookTimeoutMs?: number
+}
+
+export interface RetryPublicationSurfacesReceipt {
+	status: 'reconciled' | 'pending_retry' | 'aborted' | 'abort_failed'
+	attemptId: string
+	contentId: string
+	revisionId: string
+	previousRevisionId: string | null
+	surfaceStatus: PublicationSurfaceCommitStatus
+	surfaces: PublicationSurfaceReceipt[]
+	packageVersion: string | null
+}
+
+export type PublicationAttemptState = ContentPublicationAttemptState
+
+export interface PublicationAttempt {
+	id: string
+	operation: PublicationOperation
+	contentId: string
+	revisionId: string
+	previousRevisionId: string | null
+	state: PublicationAttemptState
+	surfaceNames: string[]
+	pendingSurfaceNames: string[]
+	preparedSurfaceNames: string[]
+	receipts: PublicationSurfaceReceipt[]
+	version: number
+	packageVersion: string | null
+	lastError: string | null
+	recoveryError?: 'invalid_durable_state'
+	createdAt: number
+	updatedAt: number
+}
+
+export interface ListPendingPublicationAttemptsOptions {
+	limit?: number
+	cursor?: {
+		updatedAt: number
+		id: string
+	}
+}
+
+export class PublicationReconciliationError extends Error {
+	readonly receipts: PublicationSurfaceReceipt[]
+	readonly attemptId: string | null
+
+	constructor(
+		message: string,
+		receipts: PublicationSurfaceReceipt[],
+		attemptId: string | null = null,
+	) {
+		super(message)
+		this.name = 'PublicationReconciliationError'
+		this.receipts = receipts
+		this.attemptId = attemptId
+	}
+}
+
+export class PublicationSurfaceRequirementError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = 'PublicationSurfaceRequirementError'
+	}
+}
+
+export class PublicationPointerMoveError extends Error {
+	readonly receipts: PublicationSurfaceReceipt[]
+	readonly attemptId: string | null
+
+	constructor(
+		message: string,
+		receipts: PublicationSurfaceReceipt[] = [],
+		attemptId: string | null = null,
+	) {
+		super(message)
+		this.name = 'PublicationPointerMoveError'
+		this.receipts = receipts
+		this.attemptId = attemptId
+	}
+}
+
+export class PublicationNotFoundError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = 'PublicationNotFoundError'
+	}
+}
+
+class PublicationAttemptConflictError extends Error {
+	readonly current: PublicationAttempt
+
+	constructor(current: PublicationAttempt) {
+		super(`publication attempt advanced concurrently to ${current.state}`)
+		this.name = 'PublicationAttemptConflictError'
+		this.current = current
+	}
+}
+
+class PublicationAttemptSupersededError extends PublicationPointerMoveError {
+	constructor(attempt: PublicationAttempt) {
+		super(
+			'publication attempt was superseded by a newer canonical revision',
+			attempt.receipts,
+			attempt.id,
+		)
+		this.name = 'PublicationAttemptSupersededError'
+	}
+}
+
+export interface ContentArchiveInput {
+	schema?: string
+	source?: string
+	items?: ContentArchiveItem[]
+}
+
+export interface ContentArchiveItem {
+	type?: ContentType
+	slug?: string
+	title?: string
+	excerpt?: string | null
+	primaryCategory?: string | null
+	primaryTopic?: string | null
+	tags?: string[]
+	bodyMarkdown?: string
+}
+
+export interface ImportContentArchiveOptions {
+	defaultPrimaryCategory?: string | null
+	defaultPrimaryTopic?: string | null
+	cursor?: number | string | null
+	batchSize?: number
+	maxBatchItems?: number
+	maxArchiveItems?: number
+	maxBodyBytes?: number
+}
+
+export interface ImportedArchiveItem {
+	id: string
+	slug: string
+	type: 'article' | 'newsletter' | 'page'
+}
+
+export interface SkippedArchiveItem {
+	index: number
+	reason: string
+	title: string | null
+	slug?: string | null
+	existingId?: string | null
+}
+
+export interface ImportContentArchiveResult {
+	created: ImportedArchiveItem[]
+	skipped: SkippedArchiveItem[]
+	processed: number
+	cursor: number
+	nextCursor: number | null
+	done: boolean
+	checkpoint: {
+		cursor: number
+		nextCursor: number | null
+		batchSize: number
+		totalItems: number
+	}
+}
+
+export class ContentArchiveImportLimitError extends Error {
+	readonly code: string
+	readonly limit: number
+	readonly actual: number
+
+	constructor(code: string, message: string, limit: number, actual: number) {
+		super(message)
+		this.name = 'ContentArchiveImportLimitError'
+		this.code = code
+		this.limit = limit
+		this.actual = actual
+	}
+}
+
+function nowSeconds(): number {
+	return Math.floor(Date.now() / 1000)
+}
+
+export const DEFAULT_PUBLICATION_SURFACE_HOOK_TIMEOUT_MS = 10_000
+export const MAX_PUBLICATION_SURFACE_HOOK_TIMEOUT_MS = 30_000
+export const DEFAULT_PENDING_PUBLICATION_ATTEMPT_LIMIT = 100
+export const MAX_PENDING_PUBLICATION_ATTEMPT_LIMIT = 500
+const MAX_PUBLICATION_ATTEMPT_JSON_BYTES = 64 * 1024
+
+function normalizeSurfaceHookTimeoutMs(value: number | undefined): number {
+	const timeoutMs = value ?? DEFAULT_PUBLICATION_SURFACE_HOOK_TIMEOUT_MS
+	if (
+		!Number.isSafeInteger(timeoutMs) ||
+		timeoutMs <= 0 ||
+		timeoutMs > MAX_PUBLICATION_SURFACE_HOOK_TIMEOUT_MS
+	) {
+		throw new PublicationSurfaceRequirementError(
+			`surfaceHookTimeoutMs must be an integer between 1 and ${MAX_PUBLICATION_SURFACE_HOOK_TIMEOUT_MS}`,
+		)
+	}
+	return timeoutMs
+}
+
+function d1Changes(result: D1Result): number | null {
+	const changes = result.meta?.changes
+	return typeof changes === 'number' ? changes : null
+}
+
+const DURABLE_DIAGNOSTIC_MAX_LENGTH = 64
+const DURABLE_DIAGNOSTICS = [
+	'abort hook not implemented',
+	'abort_hook_not_implemented',
+	'canonical_pointer_advanced',
+	'canonical_pointer_move_abort_incomplete',
+	'canonical_pointer_move_failed',
+	'invalid_surface_receipt_duration',
+	'invalid_surface_receipt_message',
+	'invalid_surface_receipt_name',
+	'invalid_surface_receipt_object',
+	'invalid surface receipt status',
+	'invalid_durable_state',
+	'surface abort failed',
+	'surface_abort_incomplete',
+	'surface_commit_failed',
+	'surface_hook_failed',
+	'surface_hook_skipped',
+	'surface_hook_timed_out',
+	'surface_hook_threw',
+	'surface_prepare_failed',
+	'untrusted_diagnostic_redacted',
+] as const
+type DurableDiagnostic = (typeof DURABLE_DIAGNOSTICS)[number]
+const DURABLE_DIAGNOSTIC_SET = new Set<string>(DURABLE_DIAGNOSTICS)
+
+function durableDiagnostic(code: DurableDiagnostic): string {
+	if (code.length > DURABLE_DIAGNOSTIC_MAX_LENGTH) {
+		throw new PublicationReconciliationError('durable diagnostic exceeds its fixed bound', [])
+	}
+	return code
+}
+
+function normalizeStoredDiagnostic(value: string): string {
+	return value.length <= DURABLE_DIAGNOSTIC_MAX_LENGTH && DURABLE_DIAGNOSTIC_SET.has(value)
+		? value
+		: durableDiagnostic('untrusted_diagnostic_redacted')
+}
+
+function parseStringArray(value: string, field: string): string[] {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(value)
+	} catch {
+		throw new PublicationReconciliationError(`publication attempt has invalid ${field}`, [])
+	}
+	if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== 'string')) {
+		throw new PublicationReconciliationError(`publication attempt has invalid ${field}`, [])
+	}
+	return parsed
+}
+
+function parseReceipts(value: string): PublicationSurfaceReceipt[] {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(value)
+	} catch {
+		throw new PublicationReconciliationError('publication attempt has invalid receipts_json', [])
+	}
+	if (!Array.isArray(parsed)) {
+		throw new PublicationReconciliationError('publication attempt has invalid receipts_json', [])
+	}
+	const receipts: PublicationSurfaceReceipt[] = []
+	for (const receipt of parsed) {
+		const candidate = receipt as {
+			name?: unknown
+			status?: unknown
+			phase?: unknown
+			message?: unknown
+			durationMs?: unknown
+		}
+		if (
+			typeof receipt !== 'object' ||
+			receipt === null ||
+			typeof candidate.name !== 'string' ||
+			(candidate.status !== 'ok' &&
+				candidate.status !== 'skipped' &&
+				candidate.status !== 'failed') ||
+			(candidate.phase !== undefined &&
+				candidate.phase !== 'prepare' &&
+				candidate.phase !== 'commit' &&
+				candidate.phase !== 'abort') ||
+			(candidate.message !== undefined && typeof candidate.message !== 'string') ||
+			(candidate.durationMs !== undefined &&
+				(typeof candidate.durationMs !== 'number' ||
+					!Number.isFinite(candidate.durationMs) ||
+					candidate.durationMs < 0))
+		) {
+			throw new PublicationReconciliationError('publication attempt has invalid receipts_json', [])
+		}
+		receipts.push({
+			name: candidate.name,
+			status: candidate.status,
+			phase: candidate.phase,
+			message:
+				typeof candidate.message === 'string'
+					? normalizeStoredDiagnostic(candidate.message)
+					: undefined,
+			durationMs: candidate.durationMs,
+		})
+	}
+	return receipts
+}
+
+function compactPublicationReceipts(
+	receipts: readonly PublicationSurfaceReceipt[],
+): PublicationSurfaceReceipt[] {
+	const compacted: PublicationSurfaceReceipt[] = []
+	const indexes = new Map<string, number>()
+	for (const receipt of receipts) {
+		const key = JSON.stringify([receipt.name, receipt.phase ?? null])
+		const existingIndex = indexes.get(key)
+		if (existingIndex === undefined) {
+			indexes.set(key, compacted.length)
+			compacted.push(receipt)
+		} else {
+			compacted[existingIndex] = receipt
+		}
+	}
+	return compacted
+}
+
+function decodeAttempt(row: ContentPublicationAttemptRow): PublicationAttempt {
+	return {
+		id: row.id,
+		operation: row.operation,
+		contentId: row.content_id,
+		revisionId: row.revision_id,
+		previousRevisionId: row.previous_revision_id,
+		state: row.state,
+		surfaceNames: parseStringArray(row.surface_names_json, 'surface_names_json'),
+		pendingSurfaceNames: parseStringArray(
+			row.pending_surface_names_json,
+			'pending_surface_names_json',
+		),
+		preparedSurfaceNames: parseStringArray(
+			row.prepared_surface_names_json,
+			'prepared_surface_names_json',
+		),
+		receipts: parseReceipts(row.receipts_json),
+		version: row.version,
+		packageVersion: row.package_version,
+		lastError: row.last_error === null ? null : normalizeStoredDiagnostic(row.last_error),
+		createdAt: row.created_at,
+		updatedAt: row.updated_at,
+	}
+}
+
+function recoverStringArray(value: string): string[] {
+	try {
+		const parsed: unknown = JSON.parse(value)
+		return Array.isArray(parsed) && parsed.every((item) => typeof item === 'string') ? parsed : []
+	} catch {
+		return []
+	}
+}
+
+function decodeAttemptForEnumeration(row: ContentPublicationAttemptRow): PublicationAttempt {
+	try {
+		return decodeAttempt(row)
+	} catch {
+		const diagnostic = durableDiagnostic('invalid_durable_state')
+		return {
+			id: row.id,
+			operation: row.operation,
+			contentId: row.content_id,
+			revisionId: row.revision_id,
+			previousRevisionId: row.previous_revision_id,
+			state: row.state,
+			surfaceNames: recoverStringArray(row.surface_names_json),
+			pendingSurfaceNames: recoverStringArray(row.pending_surface_names_json),
+			preparedSurfaceNames: recoverStringArray(row.prepared_surface_names_json),
+			receipts: [{ name: 'publication_attempt', status: 'failed', message: diagnostic }],
+			version: row.version,
+			packageVersion: row.package_version,
+			lastError: diagnostic,
+			recoveryError: 'invalid_durable_state',
+			createdAt: row.created_at,
+			updatedAt: row.updated_at,
+		}
+	}
+}
+
+async function getPublicationAttempt(
+	db: D1Database,
+	attemptId: string,
+): Promise<PublicationAttempt> {
+	const row = await db
+		.prepare(
+			`SELECT id, operation, content_id, revision_id, previous_revision_id, state,
+			        surface_names_json, pending_surface_names_json,
+			        prepared_surface_names_json, receipts_json, version,
+			        package_version, last_error, created_at, updated_at
+			 FROM content_publication_attempts
+			 WHERE id = ?`,
+		)
+		.bind(attemptId)
+		.first<ContentPublicationAttemptRow>()
+	if (!row) throw new PublicationNotFoundError(`publication attempt not found: ${attemptId}`)
+	return decodeAttempt(row)
+}
+
+export async function listPendingPublicationAttempts(
+	db: D1Database,
+	options: ListPendingPublicationAttemptsOptions = {},
+): Promise<PublicationAttempt[]> {
+	const limit = options.limit ?? DEFAULT_PENDING_PUBLICATION_ATTEMPT_LIMIT
+	if (!Number.isSafeInteger(limit) || limit <= 0 || limit > MAX_PENDING_PUBLICATION_ATTEMPT_LIMIT) {
+		throw new PublicationSurfaceRequirementError(
+			`pending publication attempt limit must be an integer between 1 and ${MAX_PENDING_PUBLICATION_ATTEMPT_LIMIT}`,
+		)
+	}
+	const cursor = options.cursor
+	if (
+		cursor &&
+		(!Number.isSafeInteger(cursor.updatedAt) ||
+			cursor.updatedAt < 0 ||
+			typeof cursor.id !== 'string' ||
+			cursor.id.length === 0)
+	) {
+		throw new PublicationSurfaceRequirementError(
+			'pending publication attempt cursor must contain a non-negative updatedAt and id',
+		)
+	}
+	const cursorClause = cursor ? 'AND (updated_at > ? OR (updated_at = ? AND id > ?))' : ''
+	const result = await db
+		.prepare(
+			`SELECT id, operation, content_id, revision_id, previous_revision_id, state,
+			        CASE WHEN length(CAST(surface_names_json AS BLOB)) <= ${MAX_PUBLICATION_ATTEMPT_JSON_BYTES}
+			             THEN surface_names_json ELSE 'null' END AS surface_names_json,
+			        CASE WHEN length(CAST(pending_surface_names_json AS BLOB)) <= ${MAX_PUBLICATION_ATTEMPT_JSON_BYTES}
+			             THEN pending_surface_names_json ELSE 'null' END AS pending_surface_names_json,
+			        CASE WHEN length(CAST(prepared_surface_names_json AS BLOB)) <= ${MAX_PUBLICATION_ATTEMPT_JSON_BYTES}
+			             THEN prepared_surface_names_json ELSE 'null' END AS prepared_surface_names_json,
+			        CASE WHEN length(CAST(receipts_json AS BLOB)) <= ${MAX_PUBLICATION_ATTEMPT_JSON_BYTES}
+			             THEN receipts_json ELSE 'null' END AS receipts_json,
+			        version,
+			        package_version, last_error, created_at, updated_at
+			 FROM content_publication_attempts
+			 WHERE (
+			   state IN ('preparing', 'prepared', 'aborting', 'abort_failed')
+			   OR (
+			      state IN ('committing', 'pending_retry')
+			      AND EXISTS (
+			        SELECT 1 FROM content_items
+			        WHERE content_items.id = content_publication_attempts.content_id
+			          AND content_items.published_revision_id = content_publication_attempts.revision_id
+			      )
+			   )
+			 )
+			 ${cursorClause}
+			 ORDER BY updated_at ASC, id ASC
+			 LIMIT ?`,
+		)
+		.bind(...(cursor ? [cursor.updatedAt, cursor.updatedAt, cursor.id, limit] : [limit]))
+		.all<ContentPublicationAttemptRow>()
+	return (result.results ?? []).map(decodeAttemptForEnumeration)
+}
+
+async function createPublicationAttempt(
+	db: D1Database,
+	input: {
+		operation: PublicationOperation
+		contentId: string
+		revisionId: string
+		previousRevisionId: string | null
+		surfaceNames: string[]
+		packageVersion: string | null
+		now: number
+	},
+): Promise<PublicationAttempt> {
+	const id = crypto.randomUUID()
+	await publicationAttemptInsert(db, id, input).run()
+	return getPublicationAttempt(db, id)
+}
+
+function publicationAttemptInsert(
+	db: D1Database,
+	id: string,
+	input: {
+		operation: PublicationOperation
+		contentId: string
+		revisionId: string
+		previousRevisionId: string | null
+		surfaceNames: string[]
+		packageVersion: string | null
+		now: number
+	},
+) {
+	return db
+		.prepare(
+			`INSERT INTO content_publication_attempts (
+			   id, operation, content_id, revision_id, previous_revision_id, state,
+			   surface_names_json, pending_surface_names_json,
+			   prepared_surface_names_json, receipts_json,
+			   package_version, created_at, updated_at
+			 ) VALUES (?, ?, ?, ?, ?, 'preparing', ?, ?, '[]', '[]', ?, ?, ?)`,
+		)
+		.bind(
+			id,
+			input.operation,
+			input.contentId,
+			input.revisionId,
+			input.previousRevisionId,
+			JSON.stringify(input.surfaceNames),
+			JSON.stringify(input.surfaceNames),
+			input.packageVersion,
+			input.now,
+			input.now,
+		)
+}
+
+async function persistPublicationAttempt(
+	db: D1Database,
+	input: {
+		attemptId: string
+		expectedVersion: number
+		expectedStates: PublicationAttemptState[]
+		state: PublicationAttemptState
+		pendingSurfaceNames: string[]
+		preparedSurfaceNames: string[]
+		receipts: PublicationSurfaceReceipt[]
+		lastError?: string | null
+		now: number
+	},
+): Promise<PublicationAttempt> {
+	if (input.expectedStates.length === 0) {
+		throw new PublicationAttemptConflictError(await getPublicationAttempt(db, input.attemptId))
+	}
+	const receipts = compactPublicationReceipts(input.receipts)
+	const expectedStatePlaceholders = input.expectedStates.map(() => '?').join(', ')
+	const result = await db
+		.prepare(
+			`UPDATE content_publication_attempts
+			 SET state = ?, pending_surface_names_json = ?, prepared_surface_names_json = ?,
+			     receipts_json = ?, last_error = ?, updated_at = ?, version = version + 1
+			 WHERE id = ? AND version = ? AND state IN (${expectedStatePlaceholders})`,
+		)
+		.bind(
+			input.state,
+			JSON.stringify(input.pendingSurfaceNames),
+			JSON.stringify(input.preparedSurfaceNames),
+			JSON.stringify(receipts),
+			input.lastError ?? null,
+			input.now,
+			input.attemptId,
+			input.expectedVersion,
+			...input.expectedStates,
+		)
+		.run()
+	const changes = d1Changes(result)
+	if (changes !== null && changes !== 1) {
+		throw new PublicationAttemptConflictError(await getPublicationAttempt(db, input.attemptId))
+	}
+	const current = await getPublicationAttempt(db, input.attemptId)
+	const matchesIntendedWrite =
+		current.version === input.expectedVersion + 1 &&
+		current.state === input.state &&
+		JSON.stringify(current.pendingSurfaceNames) === JSON.stringify(input.pendingSurfaceNames) &&
+		JSON.stringify(current.preparedSurfaceNames) === JSON.stringify(input.preparedSurfaceNames) &&
+		JSON.stringify(current.receipts) === JSON.stringify(receipts) &&
+		current.lastError === (input.lastError ?? null)
+	if (!matchesIntendedWrite) throw new PublicationAttemptConflictError(current)
+	return current
+}
+
+async function createRevisionAndPublicationAttempt(
+	db: D1Database,
+	input: {
+		contentId: string
+		previousRevisionId: string | null
+		surfaceNames: string[]
+		packageVersion: string | null
+		now: number
+		createdBy?: string | null
+	},
+): Promise<{
+	revisionId: string
+	snapshot: Record<string, unknown>
+	attempt: PublicationAttempt
+}> {
+	const snapshot = await getContentSnapshot(db, input.contentId)
+	if (!snapshot) throw new PublicationNotFoundError(`content not found: ${input.contentId}`)
+	assertPublicationSnapshotBodyValid(snapshot, input.contentId)
+	const revisionId = crypto.randomUUID()
+	const attemptId = crypto.randomUUID()
+	await db.batch([
+		db
+			.prepare(
+				'INSERT INTO content_revisions (id, content_id, payload_json, created_at, created_by) VALUES (?, ?, ?, ?, ?)',
+			)
+			.bind(
+				revisionId,
+				input.contentId,
+				JSON.stringify(snapshot),
+				input.now,
+				input.createdBy ?? null,
+			),
+		publicationAttemptInsert(db, attemptId, {
+			operation: 'publish',
+			contentId: input.contentId,
+			revisionId,
+			previousRevisionId: input.previousRevisionId,
+			surfaceNames: input.surfaceNames,
+			packageVersion: input.packageVersion,
+			now: input.now,
+		}),
+	])
+	return { revisionId, snapshot, attempt: await getPublicationAttempt(db, attemptId) }
+}
+
+function assertPublicationSnapshotBodyValid(
+	snapshot: Record<string, unknown>,
+	contentId: string,
+): void {
+	const item = snapshot.item
+	if (!item || typeof item !== 'object' || Array.isArray(item)) return
+	const type = (item as { type?: unknown }).type
+	if (type !== 'article' && type !== 'newsletter' && type !== 'page') return
+	const content = snapshot.content
+	const body = content && typeof content === 'object' && !Array.isArray(content) ? content : {}
+	const bodyMarkdown = (body as { body_markdown?: unknown }).body_markdown
+	const bodyHtml = (body as { body_html?: unknown }).body_html
+	const outcome = evaluateArticleBody(
+		{
+			body_markdown: typeof bodyMarkdown === 'string' ? bodyMarkdown : null,
+			body_html: typeof bodyHtml === 'string' ? bodyHtml : null,
+		},
+		{
+			source: 'publish-one',
+			contentId,
+			requireBody: true,
+		},
+	)
+	if (!outcome.ok) throw new PublishContentValidationError(outcome)
+}
+
+function normalizeSurfaces(input: {
+	surfaces?: PublicationReconciler[]
+	allowNoSurfaces?: boolean
+	requiredSurfaceNames?: string[]
+}): PublicationReconciler[] {
+	if (!Array.isArray(input.surfaces)) {
+		throw new PublicationSurfaceRequirementError(
+			'publication surfaces must be provided explicitly; pass allowNoSurfaces for no-live-surface mode',
+		)
+	}
+	if (input.surfaces.length === 0) {
+		if (input.allowNoSurfaces) return []
+		throw new PublicationSurfaceRequirementError(
+			'publication surfaces cannot be empty unless allowNoSurfaces is true',
+		)
+	}
+	const names = new Set<string>()
+	for (const surface of input.surfaces) {
+		const name = surface.name?.trim()
+		if (!name)
+			throw new PublicationSurfaceRequirementError('publication surface names are required')
+		if (surface.name !== name) {
+			throw new PublicationSurfaceRequirementError(
+				'publication surface names must not contain surrounding whitespace',
+			)
+		}
+		if (names.has(name)) {
+			throw new PublicationSurfaceRequirementError(`duplicate publication surface: ${name}`)
+		}
+		if (typeof surface.prepare !== 'function') {
+			throw new PublicationSurfaceRequirementError(
+				`publication surface ${name} must implement prepare`,
+			)
+		}
+		if (typeof surface.commit !== 'function') {
+			throw new PublicationSurfaceRequirementError(
+				`publication surface ${name} must implement commit`,
+			)
+		}
+		names.add(name)
+	}
+	for (const requiredName of input.requiredSurfaceNames ?? []) {
+		if (!names.has(requiredName)) {
+			throw new PublicationSurfaceRequirementError(
+				`required publication surface missing: ${requiredName}`,
+			)
+		}
+	}
+	return input.surfaces
+}
+
+function normalizeRetrySurfaces(
+	surfaces: PublicationReconciler[] | undefined,
+	pendingSurfaceNames: string[],
+): PublicationReconciler[] {
+	if (pendingSurfaceNames.length === 0) {
+		if (surfaces && surfaces.length > 0) {
+			throw new PublicationSurfaceRequirementError(
+				'completed publication attempts cannot accept retry surfaces',
+			)
+		}
+		return []
+	}
+	const normalized = normalizeSurfaces({
+		surfaces,
+		requiredSurfaceNames: pendingSurfaceNames,
+	})
+	const pending = new Set(pendingSurfaceNames)
+	for (const surface of normalized) {
+		if (!pending.has(surface.name)) {
+			throw new PublicationSurfaceRequirementError(
+				`publication retry surface is not pending: ${surface.name}`,
+			)
+		}
+	}
+	return normalized
+}
+
+function withPhase(
+	input: PublicationReconciliationInput,
+	phase: PublicationSurfacePhase,
+	signal?: AbortSignal,
+): PublicationReconciliationInput {
+	return { ...input, phase, signal }
+}
+
+class PublicationSurfaceHookTimeoutError extends Error {
+	constructor() {
+		super('publication surface hook timed out')
+		this.name = 'PublicationSurfaceHookTimeoutError'
+	}
+}
+
+async function runSurfaceHook<T>(
+	hook: (input: PublicationReconciliationInput) => Promise<T>,
+	input: PublicationReconciliationInput,
+	phase: PublicationSurfacePhase,
+	timeoutMs: number,
+): Promise<T> {
+	const controller = new AbortController()
+	let timeoutId: ReturnType<typeof setTimeout> | undefined
+	const timeout = new Promise<never>((_, reject) => {
+		timeoutId = setTimeout(() => {
+			controller.abort('publication_surface_hook_timeout')
+			reject(new PublicationSurfaceHookTimeoutError())
+		}, timeoutMs)
+	})
+	try {
+		return await Promise.race([hook(withPhase(input, phase, controller.signal)), timeout])
+	} finally {
+		if (timeoutId !== undefined) clearTimeout(timeoutId)
+	}
+}
+
+function normalizeReceipt(
+	surface: PublicationReconciler,
+	phase: PublicationSurfacePhase,
+	receipt: PublicationSurfaceReceipt | undefined,
+	started: number,
+): PublicationSurfaceReceipt {
+	const durationMs = Date.now() - started
+	if (receipt === undefined) {
+		return { name: surface.name, status: 'ok', phase, durationMs }
+	}
+	if (typeof receipt !== 'object' || receipt === null) {
+		return {
+			name: surface.name,
+			status: 'failed',
+			phase,
+			message: durableDiagnostic('invalid_surface_receipt_object'),
+			durationMs,
+		}
+	}
+	if (receipt.status !== 'ok' && receipt.status !== 'skipped' && receipt.status !== 'failed') {
+		return {
+			name: surface.name,
+			status: 'failed',
+			phase,
+			message: durableDiagnostic('invalid surface receipt status'),
+			durationMs,
+		}
+	}
+	if (receipt.name !== surface.name) {
+		return {
+			name: surface.name,
+			status: 'failed',
+			phase,
+			message: durableDiagnostic('invalid_surface_receipt_name'),
+			durationMs,
+		}
+	}
+	if (receipt.message !== undefined && typeof receipt.message !== 'string') {
+		return {
+			name: surface.name,
+			status: 'failed',
+			phase,
+			message: durableDiagnostic('invalid_surface_receipt_message'),
+			durationMs,
+		}
+	}
+	const suppliedDuration = receipt.durationMs
+	if (
+		suppliedDuration !== undefined &&
+		(typeof suppliedDuration !== 'number' ||
+			!Number.isFinite(suppliedDuration) ||
+			suppliedDuration < 0)
+	) {
+		return {
+			name: surface.name,
+			status: 'failed',
+			phase,
+			message: durableDiagnostic('invalid_surface_receipt_duration'),
+			durationMs,
+		}
+	}
+	return {
+		name: surface.name,
+		status: receipt.status,
+		phase,
+		message:
+			receipt.status === 'failed'
+				? durableDiagnostic('surface_hook_failed')
+				: receipt.status === 'skipped'
+					? durableDiagnostic('surface_hook_skipped')
+					: undefined,
+		durationMs: suppliedDuration ?? durationMs,
+	}
+}
+
+async function prepareSurfaces(
+	db: D1Database,
+	attempt: PublicationAttempt,
+	surfaces: PublicationReconciler[],
+	input: PublicationReconciliationInput,
+	surfaceHookTimeoutMs: number,
+): Promise<{
+	attempt: PublicationAttempt
+	receipts: PublicationSurfaceReceipt[]
+	prepared: PublicationReconciler[]
+}> {
+	let durable = attempt
+	let receipts: PublicationSurfaceReceipt[] = [...durable.receipts]
+	let preparedNames = new Set(durable.preparedSurfaceNames)
+	surfaceLoop: for (const surface of surfaces) {
+		if (preparedNames.has(surface.name)) continue
+		if (durable.state !== 'preparing') {
+			throw new PublicationReconciliationError(
+				`publication attempt advanced concurrently to ${durable.state}`,
+				durable.receipts,
+				durable.id,
+			)
+		}
+		const started = Date.now()
+		let normalized: PublicationSurfaceReceipt
+		try {
+			normalized = normalizeReceipt(
+				surface,
+				'prepare',
+				await runSurfaceHook(
+					surface.prepare as NonNullable<PublicationReconciler['prepare']>,
+					input,
+					'prepare',
+					surfaceHookTimeoutMs,
+				),
+				started,
+			)
+		} catch (error) {
+			normalized = {
+				name: surface.name,
+				status: 'failed',
+				phase: 'prepare',
+				message: durableDiagnostic(
+					error instanceof PublicationSurfaceHookTimeoutError
+						? 'surface_hook_timed_out'
+						: 'surface_hook_threw',
+				),
+				durationMs: Date.now() - started,
+			}
+		}
+		receipts = [...durable.receipts, normalized]
+		if (normalized.status !== 'ok') {
+			let cleanupNames = new Set([...preparedNames, surface.name])
+			let claimed: PublicationAttempt
+			for (;;) {
+				try {
+					claimed = await persistPublicationAttempt(db, {
+						attemptId: durable.id,
+						expectedVersion: durable.version,
+						expectedStates: ['preparing'],
+						state: 'aborting',
+						pendingSurfaceNames: [],
+						preparedSurfaceNames: [...cleanupNames],
+						receipts,
+						lastError: durableDiagnostic('surface_prepare_failed'),
+						now: input.now,
+					})
+					break
+				} catch (error) {
+					if (!(error instanceof PublicationAttemptConflictError)) throw error
+					durable = error.current
+					if (durable.preparedSurfaceNames.includes(surface.name)) {
+						receipts = [...durable.receipts]
+						preparedNames = new Set(durable.preparedSurfaceNames)
+						continue surfaceLoop
+					}
+					if (durable.state !== 'preparing') {
+						throw new PublicationReconciliationError(
+							`publication attempt advanced concurrently to ${durable.state}`,
+							durable.receipts,
+							durable.id,
+						)
+					}
+					preparedNames = new Set(durable.preparedSurfaceNames)
+					cleanupNames = new Set([...preparedNames, surface.name])
+					receipts = [...durable.receipts, normalized]
+				}
+			}
+			const prepared = surfaces.filter((candidate) =>
+				claimed.preparedSurfaceNames.includes(candidate.name),
+			)
+			const abortReceipts = await abortSurfaces(prepared, input, surfaceHookTimeoutMs)
+			const allReceipts = [...receipts, ...abortReceipts]
+			const incompleteAborts = abortReceipts.filter((receipt) => receipt.status !== 'ok')
+			const lastError =
+				incompleteAborts.length > 0
+					? abortFailureDiagnostic(incompleteAborts, 'surface_abort_incomplete')
+					: durableDiagnostic('surface_prepare_failed')
+			let finalized: PublicationAttempt
+			try {
+				finalized = await persistPublicationAttempt(db, {
+					attemptId: claimed.id,
+					expectedVersion: claimed.version,
+					expectedStates: ['aborting'],
+					state: incompleteAborts.length > 0 ? 'abort_failed' : 'aborted',
+					pendingSurfaceNames: [],
+					preparedSurfaceNames: incompleteAborts.map((receipt) => receipt.name),
+					receipts: allReceipts,
+					lastError,
+					now: input.now,
+				})
+			} catch (error) {
+				if (!(error instanceof PublicationAttemptConflictError)) throw error
+				finalized = error.current
+			}
+			throw new PublicationReconciliationError(
+				`publication surface did not prepare: ${surface.name}`,
+				finalized.receipts,
+				finalized.id,
+			)
+		}
+		preparedNames.add(surface.name)
+		for (;;) {
+			try {
+				durable = await persistPublicationAttempt(db, {
+					attemptId: durable.id,
+					expectedVersion: durable.version,
+					expectedStates: ['preparing'],
+					state: 'preparing',
+					pendingSurfaceNames: durable.pendingSurfaceNames,
+					preparedSurfaceNames: [...preparedNames],
+					receipts,
+					now: input.now,
+				})
+				receipts = [...durable.receipts]
+				preparedNames = new Set(durable.preparedSurfaceNames)
+				break
+			} catch (error) {
+				if (!(error instanceof PublicationAttemptConflictError)) throw error
+				durable = error.current
+				if (durable.preparedSurfaceNames.includes(surface.name)) {
+					receipts = [...durable.receipts]
+					preparedNames = new Set(durable.preparedSurfaceNames)
+					break
+				}
+				if (durable.state !== 'preparing') {
+					throw new PublicationReconciliationError(
+						`publication attempt advanced concurrently to ${durable.state}`,
+						durable.receipts,
+						durable.id,
+					)
+				}
+				preparedNames = new Set([...durable.preparedSurfaceNames, surface.name])
+				receipts = [...durable.receipts, normalized]
+			}
+		}
+	}
+	for (;;) {
+		try {
+			durable = await persistPublicationAttempt(db, {
+				attemptId: durable.id,
+				expectedVersion: durable.version,
+				expectedStates: ['preparing'],
+				state: 'prepared',
+				pendingSurfaceNames: durable.surfaceNames,
+				preparedSurfaceNames: [...preparedNames],
+				receipts,
+				now: input.now,
+			})
+			break
+		} catch (error) {
+			if (!(error instanceof PublicationAttemptConflictError)) throw error
+			durable = error.current
+			if (['prepared', 'committing', 'pending_retry', 'committed'].includes(durable.state)) break
+			if (durable.state !== 'preparing') {
+				throw new PublicationReconciliationError(
+					`publication attempt advanced concurrently to ${durable.state}`,
+					durable.receipts,
+					durable.id,
+				)
+			}
+			receipts = [...durable.receipts]
+			preparedNames = new Set(durable.preparedSurfaceNames)
+		}
+	}
+	const prepared = surfaces.filter((surface) => durable.preparedSurfaceNames.includes(surface.name))
+	return { attempt: durable, receipts: durable.receipts, prepared }
+}
+
+async function commitSurfaces(
+	db: D1Database,
+	attempt: PublicationAttempt,
+	surfaces: PublicationReconciler[],
+	input: PublicationReconciliationInput,
+	surfaceHookTimeoutMs: number,
+): Promise<{
+	attempt: PublicationAttempt
+	receipts: PublicationSurfaceReceipt[]
+	pendingSurfaceNames: string[]
+}> {
+	let durable = attempt
+	let receipts: PublicationSurfaceReceipt[] = [...durable.receipts]
+	let pending = new Set(durable.pendingSurfaceNames)
+	for (const surface of surfaces) {
+		if (!pending.has(surface.name)) continue
+		const started = Date.now()
+		let normalized: PublicationSurfaceReceipt
+		try {
+			normalized = normalizeReceipt(
+				surface,
+				'commit',
+				await runSurfaceHook(
+					surface.commit as NonNullable<PublicationReconciler['commit']>,
+					input,
+					'commit',
+					surfaceHookTimeoutMs,
+				),
+				started,
+			)
+			if (normalized.status === 'skipped') normalized.status = 'failed'
+		} catch (error) {
+			normalized = {
+				name: surface.name,
+				status: 'failed',
+				phase: 'commit',
+				message: durableDiagnostic(
+					error instanceof PublicationSurfaceHookTimeoutError
+						? 'surface_hook_timed_out'
+						: 'surface_hook_threw',
+				),
+				durationMs: Date.now() - started,
+			}
+		}
+		for (;;) {
+			receipts = [...durable.receipts, normalized]
+			pending = new Set(durable.pendingSurfaceNames)
+			if (normalized.status === 'ok') pending.delete(surface.name)
+			const inProgressState = durable.state === 'pending_retry' ? 'pending_retry' : 'committing'
+			if (!['committing', 'pending_retry'].includes(durable.state)) {
+				if (durable.state === 'committed') {
+					return {
+						attempt: durable,
+						receipts: durable.receipts,
+						pendingSurfaceNames: durable.pendingSurfaceNames,
+					}
+				}
+				throw new PublicationReconciliationError(
+					`publication attempt advanced concurrently to ${durable.state}`,
+					durable.receipts,
+					durable.id,
+				)
+			}
+			try {
+				durable = await persistPublicationAttempt(db, {
+					attemptId: durable.id,
+					expectedVersion: durable.version,
+					expectedStates: [durable.state],
+					state: inProgressState,
+					pendingSurfaceNames: [...pending],
+					preparedSurfaceNames: durable.preparedSurfaceNames,
+					receipts,
+					lastError:
+						normalized.status === 'failed' ? durableDiagnostic('surface_commit_failed') : null,
+					now: input.now,
+				})
+				receipts = [...durable.receipts]
+				pending = new Set(durable.pendingSurfaceNames)
+				break
+			} catch (error) {
+				if (!(error instanceof PublicationAttemptConflictError)) throw error
+				durable = error.current
+				if (durable.state === 'committed' || !durable.pendingSurfaceNames.includes(surface.name)) {
+					receipts = [...durable.receipts]
+					pending = new Set(durable.pendingSurfaceNames)
+					break
+				}
+			}
+		}
+	}
+	for (;;) {
+		if (durable.state === 'committed') break
+		if (!['committing', 'pending_retry'].includes(durable.state)) {
+			throw new PublicationReconciliationError(
+				`publication attempt advanced concurrently to ${durable.state}`,
+				durable.receipts,
+				durable.id,
+			)
+		}
+		pending = new Set(durable.pendingSurfaceNames)
+		const pendingFailures = durable.receipts.filter(
+			(receipt) =>
+				receipt.phase === 'commit' && receipt.status === 'failed' && pending.has(receipt.name),
+		)
+		try {
+			durable = await persistPublicationAttempt(db, {
+				attemptId: durable.id,
+				expectedVersion: durable.version,
+				expectedStates: [durable.state],
+				state: pending.size > 0 ? 'pending_retry' : 'committed',
+				pendingSurfaceNames: [...pending],
+				preparedSurfaceNames: durable.preparedSurfaceNames,
+				receipts: durable.receipts,
+				lastError: pendingFailures.length > 0 ? durableDiagnostic('surface_commit_failed') : null,
+				now: input.now,
+			})
+			break
+		} catch (error) {
+			if (!(error instanceof PublicationAttemptConflictError)) throw error
+			durable = error.current
+		}
+	}
+	return {
+		attempt: durable,
+		receipts: durable.receipts,
+		pendingSurfaceNames: durable.pendingSurfaceNames,
+	}
+}
+
+async function abortSurfaces(
+	surfaces: PublicationReconciler[],
+	input: PublicationReconciliationInput,
+	surfaceHookTimeoutMs: number,
+): Promise<PublicationSurfaceReceipt[]> {
+	const receipts: PublicationSurfaceReceipt[] = []
+	for (const surface of [...surfaces].reverse()) {
+		if (!surface.abort) {
+			receipts.push({
+				name: surface.name,
+				status: 'skipped',
+				phase: 'abort',
+				message: durableDiagnostic('abort_hook_not_implemented'),
+			})
+			continue
+		}
+		const started = Date.now()
+		try {
+			receipts.push(
+				normalizeReceipt(
+					surface,
+					'abort',
+					await runSurfaceHook(surface.abort, input, 'abort', surfaceHookTimeoutMs),
+					started,
+				),
+			)
+		} catch (error) {
+			receipts.push({
+				name: surface.name,
+				status: 'failed',
+				phase: 'abort',
+				message: durableDiagnostic(
+					error instanceof PublicationSurfaceHookTimeoutError
+						? 'surface_hook_timed_out'
+						: 'surface_hook_threw',
+				),
+				durationMs: Date.now() - started,
+			})
+		}
+	}
+	return receipts
+}
+
+function abortFailureDiagnostic(
+	receipts: PublicationSurfaceReceipt[],
+	fallback: DurableDiagnostic,
+): string {
+	if (receipts.some((receipt) => receipt.message === 'abort_hook_not_implemented')) {
+		return durableDiagnostic('abort hook not implemented')
+	}
+	if (receipts.some((receipt) => receipt.message === 'surface_hook_failed')) {
+		return durableDiagnostic('surface abort failed')
+	}
+	return durableDiagnostic(fallback)
+}
+
+async function retryAbortCleanup(
+	db: D1Database,
+	attempt: PublicationAttempt,
+	surfaces: PublicationReconciler[],
+	input: PublicationReconciliationInput,
+	surfaceHookTimeoutMs: number,
+): Promise<RetryPublicationSurfacesReceipt> {
+	let claimed: PublicationAttempt
+	try {
+		claimed = await persistPublicationAttempt(db, {
+			attemptId: attempt.id,
+			expectedVersion: attempt.version,
+			expectedStates: [attempt.state],
+			state: 'aborting',
+			pendingSurfaceNames: [],
+			preparedSurfaceNames: attempt.preparedSurfaceNames,
+			receipts: attempt.receipts,
+			lastError: attempt.lastError,
+			now: input.now,
+		})
+	} catch (error) {
+		if (!(error instanceof PublicationAttemptConflictError)) throw error
+		if (error.current.state === 'aborted') {
+			return {
+				status: 'aborted',
+				attemptId: error.current.id,
+				contentId: error.current.contentId,
+				revisionId: error.current.revisionId,
+				previousRevisionId: error.current.previousRevisionId,
+				surfaceStatus: 'none',
+				surfaces: error.current.receipts,
+				packageVersion: error.current.packageVersion,
+			}
+		}
+		throw new PublicationReconciliationError(
+			`publication cleanup advanced concurrently to ${error.current.state}`,
+			error.current.receipts,
+			error.current.id,
+		)
+	}
+	const preparedNames = new Set(claimed.preparedSurfaceNames)
+	const abortReceipts = await abortSurfaces(
+		surfaces.filter((surface) => preparedNames.has(surface.name)),
+		input,
+		surfaceHookTimeoutMs,
+	)
+	const receipts = [...claimed.receipts, ...abortReceipts]
+	const incompleteAborts = abortReceipts.filter((receipt) => receipt.status !== 'ok')
+	const lastError =
+		incompleteAborts.length > 0
+			? abortFailureDiagnostic(incompleteAborts, 'surface_abort_incomplete')
+			: null
+	let finalized: PublicationAttempt
+	try {
+		finalized = await persistPublicationAttempt(db, {
+			attemptId: claimed.id,
+			expectedVersion: claimed.version,
+			expectedStates: ['aborting'],
+			state: incompleteAborts.length > 0 ? 'abort_failed' : 'aborted',
+			pendingSurfaceNames: [],
+			preparedSurfaceNames: incompleteAborts.map((receipt) => receipt.name),
+			receipts,
+			lastError,
+			now: input.now,
+		})
+	} catch (error) {
+		if (!(error instanceof PublicationAttemptConflictError)) throw error
+		if (!['aborted', 'abort_failed'].includes(error.current.state)) {
+			throw new PublicationReconciliationError(
+				`publication cleanup advanced concurrently to ${error.current.state}`,
+				error.current.receipts,
+				error.current.id,
+			)
+		}
+		finalized = error.current
+	}
+	return {
+		status: finalized.state === 'aborted' ? 'aborted' : 'abort_failed',
+		attemptId: finalized.id,
+		contentId: finalized.contentId,
+		revisionId: finalized.revisionId,
+		previousRevisionId: finalized.previousRevisionId,
+		surfaceStatus: 'none',
+		surfaces: finalized.receipts,
+		packageVersion: finalized.packageVersion,
+	}
+}
+
+function surfaceStatusFor(surfaceNames: string[], pendingSurfaceNames: string[]) {
+	if (surfaceNames.length === 0) return 'none' satisfies PublicationSurfaceCommitStatus
+	return pendingSurfaceNames.length > 0
+		? ('pending_retry' satisfies PublicationSurfaceCommitStatus)
+		: ('committed' satisfies PublicationSurfaceCommitStatus)
+}
+
+async function assertRevisionWasCanonical(
+	db: D1Database,
+	contentId: string,
+	revisionId: string,
+): Promise<void> {
+	const provenance = await db
+		.prepare(
+			`SELECT id
+			 FROM content_publication_attempts
+			 WHERE content_id = ? AND revision_id = ?
+			   AND state IN ('committing', 'pending_retry', 'committed', 'superseded')
+			 LIMIT 1`,
+		)
+		.bind(contentId, revisionId)
+		.first<{ id: string }>()
+	if (!provenance) {
+		throw new PublicationNotFoundError(
+			`rollback target revision never became canonical: ${revisionId}`,
+		)
+	}
+}
+
+async function supersedePublicationAttempt(
+	db: D1Database,
+	attempt: PublicationAttempt,
+	now: number,
+): Promise<PublicationAttempt> {
+	let durable = attempt
+	for (;;) {
+		if (durable.state === 'superseded' || durable.state === 'committed') return durable
+		if (!['committing', 'pending_retry'].includes(durable.state)) {
+			throw new PublicationReconciliationError(
+				`publication attempt cannot be superseded from state ${durable.state}`,
+				durable.receipts,
+				durable.id,
+			)
+		}
+		try {
+			return await persistPublicationAttempt(db, {
+				attemptId: durable.id,
+				expectedVersion: durable.version,
+				expectedStates: [durable.state],
+				state: 'superseded',
+				pendingSurfaceNames: [],
+				preparedSurfaceNames: durable.preparedSurfaceNames,
+				receipts: durable.receipts,
+				lastError: durableDiagnostic('canonical_pointer_advanced'),
+				now,
+			})
+		} catch (error) {
+			if (!(error instanceof PublicationAttemptConflictError)) throw error
+			durable = error.current
+		}
+	}
+}
+
+async function claimPrecanonicalAttemptForCleanup(
+	db: D1Database,
+	attempt: PublicationAttempt,
+	now: number,
+): Promise<PublicationAttempt> {
+	let durable = attempt
+	for (;;) {
+		if (durable.state === 'aborting' || durable.state === 'abort_failed') return durable
+		if (!['preparing', 'prepared'].includes(durable.state)) {
+			throw new PublicationReconciliationError(
+				`publication attempt cannot enter stale cleanup from state ${durable.state}`,
+				durable.receipts,
+				durable.id,
+			)
+		}
+		try {
+			return await persistPublicationAttempt(db, {
+				attemptId: durable.id,
+				expectedVersion: durable.version,
+				expectedStates: [durable.state],
+				state: 'aborting',
+				pendingSurfaceNames: [],
+				preparedSurfaceNames: durable.preparedSurfaceNames,
+				receipts: durable.receipts,
+				lastError: durableDiagnostic('canonical_pointer_advanced'),
+				now,
+			})
+		} catch (error) {
+			if (!(error instanceof PublicationAttemptConflictError)) throw error
+			durable = error.current
+		}
+	}
+}
+
+async function movePointerAndBeginCommit(
+	db: D1Database,
+	attempt: PublicationAttempt,
+	now: number,
+): Promise<void> {
+	const pointerStatement =
+		attempt.operation === 'publish'
+			? db
+					.prepare(
+						`UPDATE content_items
+						 SET status = 'published', published_at = ?, publish_at = NULL,
+						     published_revision_id = ?, updated_at = unixepoch()
+						 WHERE id = ?
+						   AND COALESCE(published_revision_id, '') = ?
+						   AND EXISTS (
+						     SELECT 1 FROM content_publication_attempts
+						     WHERE id = ? AND state = 'prepared' AND revision_id = ? AND content_id = ?
+						   )`,
+					)
+					.bind(
+						now,
+						attempt.revisionId,
+						attempt.contentId,
+						attempt.previousRevisionId ?? '',
+						attempt.id,
+						attempt.revisionId,
+						attempt.contentId,
+					)
+			: db
+					.prepare(
+						`UPDATE content_items
+						 SET status = 'published', publish_at = NULL,
+						     published_revision_id = ?, updated_at = unixepoch()
+						 WHERE id = ?
+						   AND COALESCE(published_revision_id, '') = ?
+						   AND EXISTS (
+						     SELECT 1 FROM content_publication_attempts
+						     WHERE id = ? AND state = 'prepared' AND revision_id = ? AND content_id = ?
+						   )`,
+					)
+					.bind(
+						attempt.revisionId,
+						attempt.contentId,
+						attempt.previousRevisionId ?? '',
+						attempt.id,
+						attempt.revisionId,
+						attempt.contentId,
+					)
+	const attemptStatement = db
+		.prepare(
+			`UPDATE content_publication_attempts
+			 SET state = 'committing', updated_at = ?, version = version + 1
+			 WHERE id = ? AND state = 'prepared' AND version = ?
+			   AND EXISTS (
+			     SELECT 1 FROM content_items
+			     WHERE id = ? AND published_revision_id = ?
+			   )`,
+		)
+		.bind(now, attempt.id, attempt.version, attempt.contentId, attempt.revisionId)
+	const [pointerResult, attemptResult] = await db.batch([pointerStatement, attemptStatement])
+	const pointerChanges = pointerResult ? d1Changes(pointerResult) : 0
+	const attemptChanges = attemptResult ? d1Changes(attemptResult) : 0
+	const [item, durableAttempt] = await Promise.all([
+		getContentItem(db, attempt.contentId),
+		getPublicationAttempt(db, attempt.id),
+	])
+	const canonicalMatches = item?.published_revision_id === attempt.revisionId
+	if (
+		canonicalMatches &&
+		['committing', 'pending_retry', 'committed'].includes(durableAttempt.state)
+	) {
+		return
+	}
+	if (!canonicalMatches && durableAttempt.state === 'committed') return
+	if (!canonicalMatches && ['committing', 'pending_retry'].includes(durableAttempt.state)) {
+		const superseded = await supersedePublicationAttempt(db, durableAttempt, now)
+		throw new PublicationAttemptSupersededError(superseded)
+	}
+	if (durableAttempt.state === 'superseded') {
+		throw new PublicationAttemptSupersededError(durableAttempt)
+	}
+	if (canonicalMatches && durableAttempt.state === 'prepared') {
+		await persistPublicationAttempt(db, {
+			attemptId: durableAttempt.id,
+			expectedVersion: durableAttempt.version,
+			expectedStates: ['prepared'],
+			state: 'committing',
+			pendingSurfaceNames: durableAttempt.pendingSurfaceNames,
+			preparedSurfaceNames: durableAttempt.preparedSurfaceNames,
+			receipts: durableAttempt.receipts,
+			now,
+		})
+		return
+	}
+	if (
+		(pointerChanges !== null && pointerChanges !== 1) ||
+		(attemptChanges !== null && attemptChanges !== 1)
+	) {
+		throw new PublicationPointerMoveError(
+			`canonical pointer changed before ${attempt.operation} move`,
+			attempt.receipts,
+			attempt.id,
+		)
+	}
+	if (!canonicalMatches || durableAttempt.state !== 'committing') {
+		throw new PublicationPointerMoveError(
+			`canonical pointer and durable attempt did not begin ${attempt.operation} commit`,
+			attempt.receipts,
+			attempt.id,
+		)
+	}
+}
+
+async function abortAfterPointerFailure(
+	db: D1Database,
+	attempt: PublicationAttempt,
+	preparedSurfaces: PublicationReconciler[],
+	reconciliationInput: PublicationReconciliationInput,
+	receipts: PublicationSurfaceReceipt[],
+	surfaceHookTimeoutMs: number,
+): Promise<never> {
+	let claimed: PublicationAttempt
+	try {
+		claimed = await persistPublicationAttempt(db, {
+			attemptId: attempt.id,
+			expectedVersion: attempt.version,
+			expectedStates: ['prepared'],
+			state: 'aborting',
+			pendingSurfaceNames: [],
+			preparedSurfaceNames: attempt.preparedSurfaceNames,
+			receipts,
+			lastError: durableDiagnostic('canonical_pointer_move_failed'),
+			now: reconciliationInput.now,
+		})
+	} catch (claimError) {
+		if (!(claimError instanceof PublicationAttemptConflictError)) throw claimError
+		if (
+			['committing', 'pending_retry', 'committed', 'superseded'].includes(claimError.current.state)
+		) {
+			throw new PublicationAttemptSupersededError(claimError.current)
+		}
+		throw new PublicationReconciliationError(
+			`publication attempt advanced concurrently to ${claimError.current.state}`,
+			claimError.current.receipts,
+			claimError.current.id,
+		)
+	}
+	const preparedNames = new Set(claimed.preparedSurfaceNames)
+	const abortReceipts = await abortSurfaces(
+		preparedSurfaces.filter((surface) => preparedNames.has(surface.name)),
+		reconciliationInput,
+		surfaceHookTimeoutMs,
+	)
+	const allReceipts = [...receipts, ...abortReceipts]
+	const incompleteAborts = abortReceipts.filter((receipt) => receipt.status !== 'ok')
+	const lastError = durableDiagnostic(
+		incompleteAborts.length > 0
+			? 'canonical_pointer_move_abort_incomplete'
+			: 'canonical_pointer_move_failed',
+	)
+	let finalized: PublicationAttempt
+	try {
+		finalized = await persistPublicationAttempt(db, {
+			attemptId: claimed.id,
+			expectedVersion: claimed.version,
+			expectedStates: ['aborting'],
+			state: incompleteAborts.length > 0 ? 'abort_failed' : 'aborted',
+			pendingSurfaceNames: [],
+			preparedSurfaceNames: incompleteAborts.map((receipt) => receipt.name),
+			receipts: allReceipts,
+			lastError,
+			now: reconciliationInput.now,
+		})
+	} catch (finalizeError) {
+		if (!(finalizeError instanceof PublicationAttemptConflictError)) throw finalizeError
+		finalized = finalizeError.current
+	}
+	throw new PublicationPointerMoveError(
+		`canonical pointer did not move for ${finalized.operation}`,
+		finalized.receipts,
+		finalized.id,
+	)
+}
+
+export async function publishOne(
+	db: D1Database,
+	input: PublishOneInput,
+): Promise<PublishOneReceipt> {
+	const now = input.now ?? nowSeconds()
+	const surfaceHookTimeoutMs = normalizeSurfaceHookTimeoutMs(input.surfaceHookTimeoutMs)
+	const surfaces = normalizeSurfaces(input)
+	const item = await getContentItem(db, input.contentId)
+	if (!item) throw new PublicationNotFoundError(`content not found: ${input.contentId}`)
+	const previousRevisionId = item.published_revision_id
+	const { revisionId, snapshot, attempt } = await createRevisionAndPublicationAttempt(db, {
+		contentId: input.contentId,
+		previousRevisionId,
+		surfaceNames: surfaces.map((surface) => surface.name),
+		packageVersion: input.packageVersion ?? null,
+		now,
+		createdBy: input.createdBy,
+	})
+	const reconciliationInput: PublicationReconciliationInput = {
+		operation: 'publish',
+		contentId: input.contentId,
+		revisionId,
+		previousRevisionId,
+		snapshot,
+		now,
+		packageVersion: input.packageVersion ?? null,
+	}
+	const prepared = await prepareSurfaces(
+		db,
+		attempt,
+		surfaces,
+		reconciliationInput,
+		surfaceHookTimeoutMs,
+	)
+	const durablePrepared = await getPublicationAttempt(db, attempt.id)
+	try {
+		await movePointerAndBeginCommit(db, durablePrepared, now)
+	} catch (error) {
+		if (error instanceof PublicationAttemptSupersededError) throw error
+		return abortAfterPointerFailure(
+			db,
+			durablePrepared,
+			prepared.prepared,
+			reconciliationInput,
+			prepared.receipts,
+			surfaceHookTimeoutMs,
+		)
+	}
+	const afterMove = await getPublicationAttempt(db, attempt.id)
+	const pendingAfterMove = new Set(afterMove.pendingSurfaceNames)
+	const committed = await commitSurfaces(
+		db,
+		afterMove,
+		surfaces.filter((surface) => pendingAfterMove.has(surface.name)),
+		reconciliationInput,
+		surfaceHookTimeoutMs,
+	)
+	const surfaceStatus = surfaceStatusFor(attempt.surfaceNames, committed.pendingSurfaceNames)
+	return {
+		status: 'published',
+		attemptId: attempt.id,
+		contentId: input.contentId,
+		revisionId,
+		previousRevisionId,
+		publishedAt: now,
+		surfaceStatus,
+		surfaces: committed.receipts,
+		packageVersion: input.packageVersion ?? null,
+	}
+}
+
+export async function rollbackPublication(
+	db: D1Database,
+	input: RollbackPublicationInput,
+): Promise<RollbackPublicationReceipt> {
+	const now = input.now ?? nowSeconds()
+	const surfaceHookTimeoutMs = normalizeSurfaceHookTimeoutMs(input.surfaceHookTimeoutMs)
+	const surfaces = normalizeSurfaces(input)
+	const item = await getContentItem(db, input.contentId)
+	if (!item) throw new PublicationNotFoundError(`content not found: ${input.contentId}`)
+	const target = await getRevision(db, input.contentId, input.targetRevisionId)
+	if (!target) {
+		throw new PublicationNotFoundError(`revision not found: ${input.targetRevisionId}`)
+	}
+	await assertRevisionWasCanonical(db, input.contentId, input.targetRevisionId)
+	const previousRevisionId = item.published_revision_id
+	const reconciliationInput: PublicationReconciliationInput = {
+		operation: 'rollback',
+		contentId: input.contentId,
+		revisionId: input.targetRevisionId,
+		previousRevisionId,
+		snapshot: target.payload as unknown as Record<string, unknown>,
+		now,
+		packageVersion: input.packageVersion ?? null,
+	}
+	const attempt = await createPublicationAttempt(db, {
+		operation: 'rollback',
+		contentId: input.contentId,
+		revisionId: input.targetRevisionId,
+		previousRevisionId,
+		surfaceNames: surfaces.map((surface) => surface.name),
+		packageVersion: input.packageVersion ?? null,
+		now,
+	})
+	const prepared = await prepareSurfaces(
+		db,
+		attempt,
+		surfaces,
+		reconciliationInput,
+		surfaceHookTimeoutMs,
+	)
+	const durablePrepared = await getPublicationAttempt(db, attempt.id)
+	try {
+		await movePointerAndBeginCommit(db, durablePrepared, now)
+	} catch (error) {
+		if (error instanceof PublicationAttemptSupersededError) throw error
+		return abortAfterPointerFailure(
+			db,
+			durablePrepared,
+			prepared.prepared,
+			reconciliationInput,
+			prepared.receipts,
+			surfaceHookTimeoutMs,
+		)
+	}
+	const afterMove = await getPublicationAttempt(db, attempt.id)
+	const pendingAfterMove = new Set(afterMove.pendingSurfaceNames)
+	const committed = await commitSurfaces(
+		db,
+		afterMove,
+		surfaces.filter((surface) => pendingAfterMove.has(surface.name)),
+		reconciliationInput,
+		surfaceHookTimeoutMs,
+	)
+	const surfaceStatus = surfaceStatusFor(attempt.surfaceNames, committed.pendingSurfaceNames)
+	return {
+		status: 'rolled_back',
+		attemptId: attempt.id,
+		contentId: input.contentId,
+		revisionId: input.targetRevisionId,
+		previousRevisionId,
+		rolledBackAt: now,
+		surfaceStatus,
+		surfaces: committed.receipts,
+		packageVersion: input.packageVersion ?? null,
+	}
+}
+
+export async function retryPublicationSurfaces(
+	db: D1Database,
+	input: RetryPublicationSurfacesInput,
+): Promise<RetryPublicationSurfacesReceipt> {
+	const now = input.now ?? nowSeconds()
+	const surfaceHookTimeoutMs = normalizeSurfaceHookTimeoutMs(input.surfaceHookTimeoutMs)
+	let attempt = await getPublicationAttempt(db, input.attemptId)
+	if (attempt.state === 'committed') {
+		normalizeRetrySurfaces(input.surfaces, attempt.pendingSurfaceNames)
+		return {
+			status: 'reconciled',
+			attemptId: attempt.id,
+			contentId: attempt.contentId,
+			revisionId: attempt.revisionId,
+			previousRevisionId: attempt.previousRevisionId,
+			surfaceStatus: surfaceStatusFor(attempt.surfaceNames, []),
+			surfaces: attempt.receipts,
+			packageVersion: attempt.packageVersion,
+		}
+	}
+	if (
+		!['preparing', 'prepared', 'committing', 'pending_retry', 'aborting', 'abort_failed'].includes(
+			attempt.state,
+		)
+	) {
+		throw new PublicationReconciliationError(
+			`publication attempt is not recoverable from state ${attempt.state}`,
+			attempt.receipts,
+			attempt.id,
+		)
+	}
+	const item = await getContentItem(db, attempt.contentId)
+	if (!item) throw new PublicationNotFoundError(`content not found: ${attempt.contentId}`)
+	if (
+		['committing', 'pending_retry'].includes(attempt.state) &&
+		item.published_revision_id !== attempt.revisionId
+	) {
+		attempt = await supersedePublicationAttempt(db, attempt, now)
+		throw new PublicationAttemptSupersededError(attempt)
+	}
+	const stalePrecanonicalAttempt =
+		['preparing', 'prepared'].includes(attempt.state) &&
+		item.published_revision_id !== attempt.previousRevisionId &&
+		item.published_revision_id !== attempt.revisionId
+	if (stalePrecanonicalAttempt) {
+		attempt = await claimPrecanonicalAttemptForCleanup(db, attempt, now)
+	}
+	const cleanupRecovery =
+		stalePrecanonicalAttempt || ['aborting', 'abort_failed'].includes(attempt.state)
+	const retrySurfaceInput = stalePrecanonicalAttempt
+		? input.surfaces?.filter((surface) => attempt.preparedSurfaceNames.includes(surface.name))
+		: input.surfaces
+	const surfaces = normalizeRetrySurfaces(
+		retrySurfaceInput,
+		cleanupRecovery ? attempt.preparedSurfaceNames : attempt.pendingSurfaceNames,
+	)
+	const revision = await getRevision(db, attempt.contentId, attempt.revisionId)
+	if (!revision) throw new PublicationNotFoundError(`revision not found: ${attempt.revisionId}`)
+	const reconciliationInput: PublicationReconciliationInput = {
+		operation: attempt.operation,
+		contentId: attempt.contentId,
+		revisionId: attempt.revisionId,
+		previousRevisionId: attempt.previousRevisionId,
+		snapshot: revision.payload as unknown as Record<string, unknown>,
+		now,
+		packageVersion: attempt.packageVersion,
+	}
+	if (cleanupRecovery) {
+		const cleanup = await retryAbortCleanup(
+			db,
+			attempt,
+			surfaces,
+			reconciliationInput,
+			surfaceHookTimeoutMs,
+		)
+		if (stalePrecanonicalAttempt) {
+			throw new PublicationAttemptSupersededError(
+				await getPublicationAttempt(db, cleanup.attemptId),
+			)
+		}
+		return cleanup
+	}
+	if (attempt.state === 'preparing') {
+		const prepared = await prepareSurfaces(
+			db,
+			attempt,
+			surfaces,
+			reconciliationInput,
+			surfaceHookTimeoutMs,
+		)
+		attempt = prepared.attempt
+		try {
+			await movePointerAndBeginCommit(db, attempt, now)
+		} catch (error) {
+			if (error instanceof PublicationAttemptSupersededError) throw error
+			return abortAfterPointerFailure(
+				db,
+				attempt,
+				prepared.prepared,
+				reconciliationInput,
+				prepared.receipts,
+				surfaceHookTimeoutMs,
+			)
+		}
+	} else if (attempt.state === 'prepared') {
+		try {
+			await movePointerAndBeginCommit(db, attempt, now)
+		} catch (error) {
+			if (error instanceof PublicationAttemptSupersededError) throw error
+			return abortAfterPointerFailure(
+				db,
+				attempt,
+				surfaces,
+				reconciliationInput,
+				attempt.receipts,
+				surfaceHookTimeoutMs,
+			)
+		}
+	} else if (item.published_revision_id !== attempt.revisionId) {
+		throw new PublicationPointerMoveError(
+			'canonical pointer does not match durable retry revision',
+			attempt.receipts,
+			attempt.id,
+		)
+	}
+	attempt = await getPublicationAttempt(db, attempt.id)
+	const pending = new Set(attempt.pendingSurfaceNames)
+	const committed = await commitSurfaces(
+		db,
+		attempt,
+		surfaces.filter((surface) => pending.has(surface.name)),
+		reconciliationInput,
+		surfaceHookTimeoutMs,
+	)
+	const surfaceStatus = surfaceStatusFor(attempt.surfaceNames, committed.pendingSurfaceNames)
+	return {
+		status: surfaceStatus === 'pending_retry' ? 'pending_retry' : 'reconciled',
+		attemptId: attempt.id,
+		contentId: attempt.contentId,
+		revisionId: attempt.revisionId,
+		previousRevisionId: attempt.previousRevisionId,
+		surfaceStatus,
+		surfaces: committed.receipts,
+		packageVersion: attempt.packageVersion,
+	}
+}
+
+function bodyBackedArchiveType(
+	type: ContentType | undefined,
+): 'article' | 'newsletter' | 'page' | null {
+	if (type === 'article' || type === 'newsletter' || type === 'page') return type
+	return null
+}
+
+const DEFAULT_IMPORT_BATCH_ITEMS = 100
+const DEFAULT_MAX_IMPORT_BATCH_ITEMS = 500
+const DEFAULT_MAX_ARCHIVE_ITEMS = 10_000
+const DEFAULT_MAX_ARCHIVE_BODY_BYTES = 256 * 1024
+
+function textBytes(value: string): number {
+	return new TextEncoder().encode(value).byteLength
+}
+
+function parseArchiveCursor(cursor: number | string | null | undefined): number {
+	if (cursor === null || cursor === undefined || cursor === '') return 0
+	const parsed = typeof cursor === 'number' ? cursor : Number(cursor)
+	if (!Number.isInteger(parsed) || parsed < 0) {
+		throw new ContentArchiveImportLimitError(
+			'archive_cursor_invalid',
+			'archive import cursor must be a non-negative integer',
+			0,
+			parsed,
+		)
+	}
+	return parsed
+}
+
+function assertLimit(code: string, message: string, limit: number, actual: number): void {
+	if (actual > limit) throw new ContentArchiveImportLimitError(code, message, limit, actual)
+}
+
+async function findContentBySlug(
+	db: D1Database,
+	slug: string,
+): Promise<{ id: string; slug: string; type: 'article' | 'newsletter' | 'page' } | null> {
+	const row = await db
+		.prepare('SELECT id, slug, type FROM content_items WHERE slug = ? LIMIT 1')
+		.bind(slug)
+		.first<{ id: string; slug: string; type: ContentType }>()
+	if (!row) return null
+	const type = bodyBackedArchiveType(row.type)
+	if (!type) return null
+	return { id: row.id, slug: row.slug, type }
+}
+
+function createInputForArchiveItem(
+	item: ContentArchiveItem,
+	type: 'article' | 'newsletter' | 'page',
+	slug: string,
+	options: ImportContentArchiveOptions,
+): CreateContentInput {
+	const base = {
+		type,
+		slug,
+		title: item.title ?? 'Untitled',
+		excerpt: item.excerpt ?? null,
+		primaryCategory: item.primaryCategory ?? options.defaultPrimaryCategory ?? 'analysis',
+		primaryTopic: item.primaryTopic ?? options.defaultPrimaryTopic ?? null,
+		tags: item.tags ?? [],
+		content: {
+			bodyMarkdown: item.bodyMarkdown ?? ' ',
+		},
+	}
+	if (type === 'article') return { ...base, type: 'article' }
+	if (type === 'newsletter') return { ...base, type: 'newsletter' }
+	return { ...base, type: 'page' }
+}
+
+export async function importContentArchive(
+	db: D1Database,
+	archive: ContentArchiveInput,
+	options: ImportContentArchiveOptions = {},
+): Promise<ImportContentArchiveResult> {
+	const created: ImportedArchiveItem[] = []
+	const skipped: SkippedArchiveItem[] = []
+	const items = Array.isArray(archive.items) ? archive.items : []
+	const cursor = parseArchiveCursor(options.cursor)
+	const batchSize = options.batchSize ?? DEFAULT_IMPORT_BATCH_ITEMS
+	const maxBatchItems = options.maxBatchItems ?? DEFAULT_MAX_IMPORT_BATCH_ITEMS
+	const maxArchiveItems = options.maxArchiveItems ?? DEFAULT_MAX_ARCHIVE_ITEMS
+	const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_ARCHIVE_BODY_BYTES
+	assertLimit(
+		'archive_item_limit_exceeded',
+		'archive item count exceeds the configured import limit',
+		maxArchiveItems,
+		items.length,
+	)
+	if (cursor > items.length) {
+		throw new ContentArchiveImportLimitError(
+			'archive_cursor_out_of_range',
+			'archive import cursor exceeds the archive item count',
+			items.length,
+			cursor,
+		)
+	}
+	assertLimit(
+		'archive_batch_limit_exceeded',
+		'archive import batch size exceeds the configured import limit',
+		maxBatchItems,
+		batchSize,
+	)
+	if (!Number.isInteger(batchSize) || batchSize < 1) {
+		throw new ContentArchiveImportLimitError(
+			'archive_batch_limit_invalid',
+			'archive import batch size must be a positive integer',
+			1,
+			batchSize,
+		)
+	}
+	const end = Math.min(items.length, cursor + batchSize)
+	for (let index = cursor; index < end; index += 1) {
+		const item = items[index]
+		if (!item) continue
+		const type = bodyBackedArchiveType(item.type)
+		if (!type) {
+			skipped.push({ index, reason: 'unsupported_type', title: item.title ?? null })
+			continue
+		}
+		if (!item.title?.trim()) {
+			skipped.push({ index, reason: 'missing_title', title: null })
+			continue
+		}
+		const requestedSlug = item.slug?.trim() || item.title
+		const baseSlug = slugify(requestedSlug)
+		const bodyMarkdown = item.bodyMarkdown ?? ' '
+		assertLimit(
+			'archive_body_limit_exceeded',
+			'archive item body exceeds the configured import limit',
+			maxBodyBytes,
+			textBytes(bodyMarkdown),
+		)
+		const existing = await findContentBySlug(db, baseSlug)
+		if (existing) {
+			skipped.push({
+				index,
+				reason: 'already_imported',
+				title: item.title,
+				slug: existing.slug,
+				existingId: existing.id,
+			})
+			continue
+		}
+		const slug = await ensureUniqueSlug(db, requestedSlug)
+		const result = await createContent(db, createInputForArchiveItem(item, type, slug, options))
+		created.push({ id: result.id, slug: result.slug, type })
+	}
+	const nextCursor = end >= items.length ? null : end
+	return {
+		created,
+		skipped,
+		processed: end - cursor,
+		cursor,
+		nextCursor,
+		done: nextCursor === null,
+		checkpoint: {
+			cursor,
+			nextCursor,
+			batchSize,
+			totalItems: items.length,
+		},
+	}
+}