@growth-labs/cms 0.2.0 → 0.3.0

package/src/engine/reader-state.ts

@@ -0,0 +1,918 @@
+import type { CmsReaderStateRow, ContentType, ReaderManualReadState } from '../schema/types.js'
+import type { D1Database, D1Result } from './d1.js'
+
+export const READER_AUTOMATIC_COMPLETION_BPS = 9_000
+export const DEFAULT_READER_STATE_BATCH_SIZE = 50
+export const MAX_READER_STATE_BATCH_SIZE = 100
+
+const UUIDV4_PATTERN =
+	/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/
+const ULID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/
+const SITE_ID_PATTERN = /^[a-z][a-z0-9_-]{1,63}$/
+const CONTENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,127}$/
+const MUTATION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,127}$/
+const PREFERENCE_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9._:-]{0,63}$/
+const CONTENT_TYPES = new Set<ContentType>(['article', 'video', 'podcast', 'newsletter', 'page'])
+const MAX_PREFERENCE_KEYS = 50
+const MAX_PREFERENCES_JSON_BYTES = 8_192
+const MAX_EVENT_FUTURE_SKEW_MS = 5 * 60 * 1_000
+
+/**
+ * Verified request scope supplied by the consuming site after issuer and site
+ * token validation. The package validates the canonical raw identifier shape;
+ * callers must never construct this from analytics, email, local-user, URL, or
+ * request-body identifiers.
+ */
+export interface ReaderStateScope {
+	identityUserId: string
+	siteId: string
+}
+
+export interface ContentStateKey {
+	contentType: ContentType
+	contentId: string
+}
+
+export type ReaderBehavioralConsent = 'granted' | 'denied'
+export type ReaderPreferenceValue = string | number | boolean | null
+export type ReaderPreferences = Record<string, ReaderPreferenceValue>
+
+export interface ReaderStateRecord {
+	identityUserId: string
+	siteId: string
+	contentType: ContentType
+	contentId: string
+	firstOpenedAt: number | null
+	lastOpenedAt: number | null
+	maxProgressBasisPoints: number
+	mediaPositionMs: number | null
+	mediaDurationMs: number | null
+	progressObservedAt: number | null
+	automaticCompletedAt: number | null
+	manualReadState: ReaderManualReadState | null
+	manualStateAt: number | null
+	saved: boolean
+	savedAt: number | null
+	preferences: ReaderPreferences
+	preferencesAt: number | null
+	version: number
+	effectiveRead: boolean
+	createdAt: number
+	updatedAt: number
+}
+
+export interface ReaderStateMutationResult {
+	applied: boolean
+	reason: 'applied' | 'stale'
+	state: ReaderStateRecord
+}
+
+export type ReaderStateBehaviorResult =
+	| ReaderStateMutationResult
+	| { applied: false; reason: 'consent_denied'; state: ReaderStateRecord | null }
+
+export interface ReaderStateListOptions {
+	limit?: number
+	cursor?: string | null
+}
+
+export interface ReaderStatePage {
+	items: ReaderStateRecord[]
+	nextCursor: string | null
+}
+
+export interface ReaderStateExportPage extends ReaderStatePage {
+	scope: ReaderStateScope
+	exportedAt: number
+}
+
+interface BehavioralWriteOptions {
+	behavioralConsent: ReaderBehavioralConsent
+	occurredAt?: number
+	expectedVersion?: number
+}
+
+export interface RecordReaderOpenOptions extends BehavioralWriteOptions {}
+
+export interface RecordReaderProgressOptions extends BehavioralWriteOptions {
+	progressBasisPoints: number
+	mediaPositionMs?: number
+	mediaDurationMs?: number
+}
+
+interface ExplicitMutationOptions {
+	occurredAt?: number
+	mutationId: string
+	expectedVersion?: number
+}
+
+export interface SetManualReadStateOptions extends ExplicitMutationOptions {
+	state: ReaderManualReadState
+}
+
+export interface ClearManualReadStateOptions extends ExplicitMutationOptions {}
+
+export interface SetSavedStateOptions extends ExplicitMutationOptions {
+	saved: boolean
+}
+
+export interface SetReaderPreferencesOptions extends ExplicitMutationOptions {
+	preferences: ReaderPreferences
+}
+
+interface ResolvedScope {
+	identityUserId: string
+	siteId: string
+}
+
+interface ResolvedMutation {
+	occurredAt: number
+	expectedVersion: number | undefined
+}
+
+export class ReaderStateInputError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = 'ReaderStateInputError'
+	}
+}
+
+export class ReaderStateConflictError extends Error {
+	constructor(
+		readonly expectedVersion: number,
+		readonly actualVersion: number | null,
+	) {
+		super(
+			`@growth-labs/cms reader state version conflict: expected ${expectedVersion}, actual ${actualVersion ?? 'missing'}`,
+		)
+		this.name = 'ReaderStateConflictError'
+	}
+}
+
+export class ReaderStateDurableStateError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = 'ReaderStateDurableStateError'
+	}
+}
+
+export async function getReaderState(
+	db: D1Database,
+	scope: ReaderStateScope,
+	key: ContentStateKey,
+): Promise<ReaderStateRecord | null> {
+	const resolvedScope = resolveScope(scope)
+	const resolvedKey = resolveContentKey(key)
+	return loadReaderState(db, resolvedScope, resolvedKey)
+}
+
+/** Unlock is intentionally a read-only observation: it never creates or completes state. */
+export async function recordReaderUnlock(
+	db: D1Database,
+	scope: ReaderStateScope,
+	key: ContentStateKey,
+): Promise<ReaderStateRecord | null> {
+	return getReaderState(db, scope, key)
+}
+
+export async function recordReaderOpen(
+	db: D1Database,
+	scope: ReaderStateScope,
+	key: ContentStateKey,
+	options: RecordReaderOpenOptions,
+): Promise<ReaderStateBehaviorResult> {
+	const resolvedScope = resolveScope(scope)
+	const resolvedKey = resolveContentKey(key)
+	if (resolveBehavioralConsent(options) === 'denied') {
+		return {
+			applied: false,
+			reason: 'consent_denied',
+			state: await loadReaderState(db, resolvedScope, resolvedKey),
+		}
+	}
+
+	const mutation = resolveMutation(options)
+	const { occurredAt, expectedVersion } = mutation
+	return executeMutation(
+		db,
+		resolvedScope,
+		resolvedKey,
+		occurredAt,
+		expectedVersion,
+		db
+			.prepare(
+				`UPDATE cms_reader_state
+				 SET first_opened_at = CASE
+						WHEN first_opened_at IS NULL OR first_opened_at > ? THEN ?
+						ELSE first_opened_at END,
+					 last_opened_at = CASE
+						WHEN last_opened_at IS NULL OR last_opened_at < ? THEN ?
+						ELSE last_opened_at END,
+					 version = version + 1,
+					 updated_at = CASE WHEN updated_at < ? THEN ? ELSE updated_at END
+				 WHERE identity_user_id = ? AND site_id = ? AND content_type = ? AND content_id = ?
+					AND (? IS NULL OR version = ?)
+					AND (first_opened_at IS NULL OR first_opened_at > ?
+						OR last_opened_at IS NULL OR last_opened_at < ?)
+				 RETURNING *`,
+			)
+			.bind(
+				occurredAt,
+				occurredAt,
+				occurredAt,
+				occurredAt,
+				occurredAt,
+				occurredAt,
+				resolvedScope.identityUserId,
+				resolvedScope.siteId,
+				resolvedKey.contentType,
+				resolvedKey.contentId,
+				expectedVersion ?? null,
+				expectedVersion ?? null,
+				occurredAt,
+				occurredAt,
+			),
+	)
+}
+
+export async function recordReaderProgress(
+	db: D1Database,
+	scope: ReaderStateScope,
+	key: ContentStateKey,
+	options: RecordReaderProgressOptions,
+): Promise<ReaderStateBehaviorResult> {
+	const resolvedScope = resolveScope(scope)
+	const resolvedKey = resolveContentKey(key)
+	if (resolveBehavioralConsent(options) === 'denied') {
+		return {
+			applied: false,
+			reason: 'consent_denied',
+			state: await loadReaderState(db, resolvedScope, resolvedKey),
+		}
+	}
+
+	const mutation = resolveMutation(options)
+	const progress = assertBasisPoints(options.progressBasisPoints)
+	const mediaPositionMs = optionalNonNegativeInteger(options.mediaPositionMs, 'mediaPositionMs')
+	const mediaDurationMs = optionalNonNegativeInteger(options.mediaDurationMs, 'mediaDurationMs')
+	if (
+		mediaPositionMs !== undefined &&
+		mediaDurationMs !== undefined &&
+		mediaPositionMs > mediaDurationMs
+	) {
+		throw new ReaderStateInputError('reader mediaPositionMs cannot exceed mediaDurationMs')
+	}
+	const { occurredAt, expectedVersion } = mutation
+	return executeMutation(
+		db,
+		resolvedScope,
+		resolvedKey,
+		occurredAt,
+		expectedVersion,
+		db
+			.prepare(
+				`UPDATE cms_reader_state
+				 SET max_progress_bps = CASE
+						WHEN max_progress_bps < ? THEN ? ELSE max_progress_bps END,
+					 media_position_ms = CASE
+						WHEN ? IS NOT NULL AND (progress_observed_at IS NULL OR progress_observed_at < ?)
+						THEN ? ELSE media_position_ms END,
+					 media_duration_ms = CASE
+						WHEN ? IS NOT NULL AND (progress_observed_at IS NULL OR progress_observed_at < ?)
+						THEN ? ELSE media_duration_ms END,
+					 progress_observed_at = CASE
+						WHEN progress_observed_at IS NULL OR progress_observed_at < ? THEN ?
+						ELSE progress_observed_at END,
+					 automatic_completed_at = CASE
+						WHEN automatic_completed_at IS NULL
+							AND MAX(max_progress_bps, ?) >= ${READER_AUTOMATIC_COMPLETION_BPS}
+						THEN ? ELSE automatic_completed_at END,
+					 version = version + 1,
+					 updated_at = CASE WHEN updated_at < ? THEN ? ELSE updated_at END
+				 WHERE identity_user_id = ? AND site_id = ? AND content_type = ? AND content_id = ?
+					AND (? IS NULL OR version = ?)
+					AND (max_progress_bps < ?
+						OR progress_observed_at IS NULL OR progress_observed_at < ?
+						OR (automatic_completed_at IS NULL AND ? >= ${READER_AUTOMATIC_COMPLETION_BPS}))
+				 RETURNING *`,
+			)
+			.bind(
+				progress,
+				progress,
+				mediaPositionMs ?? null,
+				occurredAt,
+				mediaPositionMs ?? null,
+				mediaDurationMs ?? null,
+				occurredAt,
+				mediaDurationMs ?? null,
+				occurredAt,
+				occurredAt,
+				progress,
+				occurredAt,
+				occurredAt,
+				occurredAt,
+				resolvedScope.identityUserId,
+				resolvedScope.siteId,
+				resolvedKey.contentType,
+				resolvedKey.contentId,
+				expectedVersion ?? null,
+				expectedVersion ?? null,
+				progress,
+				occurredAt,
+				progress,
+			),
+	)
+}
+
+export async function setManualReadState(
+	db: D1Database,
+	scope: ReaderStateScope,
+	key: ContentStateKey,
+	options: SetManualReadStateOptions,
+): Promise<ReaderStateMutationResult> {
+	if (options?.state !== 'read' && options?.state !== 'unread') {
+		throw new ReaderStateInputError('manual reader state must be "read" or "unread"')
+	}
+	return writeManualState(db, scope, key, options.state, options)
+}
+
+export async function clearManualReadState(
+	db: D1Database,
+	scope: ReaderStateScope,
+	key: ContentStateKey,
+	options: ClearManualReadStateOptions,
+): Promise<ReaderStateMutationResult> {
+	return writeManualState(db, scope, key, null, options)
+}
+
+async function writeManualState(
+	db: D1Database,
+	scope: ReaderStateScope,
+	key: ContentStateKey,
+	state: ReaderManualReadState | null,
+	options: ExplicitMutationOptions,
+): Promise<ReaderStateMutationResult> {
+	const resolvedScope = resolveScope(scope)
+	const resolvedKey = resolveContentKey(key)
+	const mutation = resolveExplicitMutation(options)
+	return executeMutation(
+		db,
+		resolvedScope,
+		resolvedKey,
+		mutation.occurredAt,
+		mutation.expectedVersion,
+		db
+			.prepare(
+				`UPDATE cms_reader_state
+				 SET manual_read_state = ?, manual_state_at = ?, manual_mutation_id = ?,
+					 version = version + 1,
+					 updated_at = CASE WHEN updated_at < ? THEN ? ELSE updated_at END
+				 WHERE identity_user_id = ? AND site_id = ? AND content_type = ? AND content_id = ?
+					AND (? IS NULL OR version = ?)
+					AND (manual_state_at IS NULL OR manual_state_at < ?
+						OR (manual_state_at = ? AND COALESCE(manual_mutation_id, '') < ?))
+				 RETURNING *`,
+			)
+			.bind(
+				state,
+				mutation.occurredAt,
+				options.mutationId,
+				mutation.occurredAt,
+				mutation.occurredAt,
+				resolvedScope.identityUserId,
+				resolvedScope.siteId,
+				resolvedKey.contentType,
+				resolvedKey.contentId,
+				mutation.expectedVersion ?? null,
+				mutation.expectedVersion ?? null,
+				mutation.occurredAt,
+				mutation.occurredAt,
+				options.mutationId,
+			),
+	)
+}
+
+export async function setSavedState(
+	db: D1Database,
+	scope: ReaderStateScope,
+	key: ContentStateKey,
+	options: SetSavedStateOptions,
+): Promise<ReaderStateMutationResult> {
+	if (typeof options?.saved !== 'boolean') {
+		throw new ReaderStateInputError('saved reader state must be a boolean')
+	}
+	const resolvedScope = resolveScope(scope)
+	const resolvedKey = resolveContentKey(key)
+	const mutation = resolveExplicitMutation(options)
+	return executeMutation(
+		db,
+		resolvedScope,
+		resolvedKey,
+		mutation.occurredAt,
+		mutation.expectedVersion,
+		db
+			.prepare(
+				`UPDATE cms_reader_state
+				 SET saved = ?, saved_at = ?, saved_mutation_id = ?,
+					 version = version + 1,
+					 updated_at = CASE WHEN updated_at < ? THEN ? ELSE updated_at END
+				 WHERE identity_user_id = ? AND site_id = ? AND content_type = ? AND content_id = ?
+					AND (? IS NULL OR version = ?)
+					AND (saved_at IS NULL OR saved_at < ?
+						OR (saved_at = ? AND COALESCE(saved_mutation_id, '') < ?))
+				 RETURNING *`,
+			)
+			.bind(
+				options.saved ? 1 : 0,
+				mutation.occurredAt,
+				options.mutationId,
+				mutation.occurredAt,
+				mutation.occurredAt,
+				resolvedScope.identityUserId,
+				resolvedScope.siteId,
+				resolvedKey.contentType,
+				resolvedKey.contentId,
+				mutation.expectedVersion ?? null,
+				mutation.expectedVersion ?? null,
+				mutation.occurredAt,
+				mutation.occurredAt,
+				options.mutationId,
+			),
+	)
+}
+
+export async function setReaderPreferences(
+	db: D1Database,
+	scope: ReaderStateScope,
+	key: ContentStateKey,
+	options: SetReaderPreferencesOptions,
+): Promise<ReaderStateMutationResult> {
+	const preferences = normalizePreferences(options?.preferences)
+	const resolvedScope = resolveScope(scope)
+	const resolvedKey = resolveContentKey(key)
+	const mutation = resolveExplicitMutation(options)
+	const preferencesJson = JSON.stringify(preferences)
+	return executeMutation(
+		db,
+		resolvedScope,
+		resolvedKey,
+		mutation.occurredAt,
+		mutation.expectedVersion,
+		db
+			.prepare(
+				`UPDATE cms_reader_state
+				 SET preferences_json = ?, preferences_at = ?, preferences_mutation_id = ?,
+					 version = version + 1,
+					 updated_at = CASE WHEN updated_at < ? THEN ? ELSE updated_at END
+				 WHERE identity_user_id = ? AND site_id = ? AND content_type = ? AND content_id = ?
+					AND (? IS NULL OR version = ?)
+					AND (preferences_at IS NULL OR preferences_at < ?
+						OR (preferences_at = ? AND COALESCE(preferences_mutation_id, '') < ?))
+				 RETURNING *`,
+			)
+			.bind(
+				preferencesJson,
+				mutation.occurredAt,
+				options.mutationId,
+				mutation.occurredAt,
+				mutation.occurredAt,
+				resolvedScope.identityUserId,
+				resolvedScope.siteId,
+				resolvedKey.contentType,
+				resolvedKey.contentId,
+				mutation.expectedVersion ?? null,
+				mutation.expectedVersion ?? null,
+				mutation.occurredAt,
+				mutation.occurredAt,
+				options.mutationId,
+			),
+	)
+}
+
+export async function getReaderStateBatch(
+	db: D1Database,
+	scope: ReaderStateScope,
+	keys: readonly ContentStateKey[],
+): Promise<ReaderStateRecord[]> {
+	const resolvedScope = resolveScope(scope)
+	if (!Array.isArray(keys)) {
+		throw new ReaderStateInputError('reader state batch keys must be an array')
+	}
+	if (keys.length > MAX_READER_STATE_BATCH_SIZE) {
+		throw new ReaderStateInputError(
+			`reader state batches are limited to ${MAX_READER_STATE_BATCH_SIZE} declared content IDs`,
+		)
+	}
+	if (keys.length === 0) return []
+	const resolvedKeys = keys.map(resolveContentKey)
+	const declared = resolvedKeys.map(() => '(content_type = ? AND content_id = ?)').join(' OR ')
+	const statement = db.prepare(
+		`SELECT * FROM cms_reader_state
+		 WHERE identity_user_id = ? AND site_id = ? AND (${declared})
+		 ORDER BY content_type, content_id`,
+	)
+	const bindings: unknown[] = [resolvedScope.identityUserId, resolvedScope.siteId]
+	for (const key of resolvedKeys) bindings.push(key.contentType, key.contentId)
+	const result = await statement.bind(...bindings).all<CmsReaderStateRow>()
+	return (result.results ?? []).map(decodeReaderStateRow)
+}
+
+export async function listReaderState(
+	db: D1Database,
+	scope: ReaderStateScope,
+	options: ReaderStateListOptions = {},
+): Promise<ReaderStatePage> {
+	const resolvedScope = resolveScope(scope)
+	return readReaderStatePage(db, resolvedScope, options, 'updated')
+}
+
+async function readReaderStatePage(
+	db: D1Database,
+	scope: ResolvedScope,
+	options: ReaderStateListOptions,
+	order: ReaderStateOrder,
+): Promise<ReaderStatePage> {
+	const limit = resolveLimit(options.limit)
+	const cursor = options.cursor ? decodeCursor(options.cursor, order) : null
+	const orderColumn = order === 'updated' ? 'updated_at' : 'created_at'
+	let statement: ReturnType<D1Database['prepare']>
+	if (cursor) {
+		statement = db
+			.prepare(
+				`SELECT * FROM cms_reader_state
+				 WHERE identity_user_id = ? AND site_id = ?
+					AND (${orderColumn} < ?
+						OR (${orderColumn} = ? AND content_type > ?)
+						OR (${orderColumn} = ? AND content_type = ? AND content_id > ?))
+				 ORDER BY ${orderColumn} DESC, content_type, content_id
+				 LIMIT ?`,
+			)
+			.bind(
+				scope.identityUserId,
+				scope.siteId,
+				cursor.orderedAt,
+				cursor.orderedAt,
+				cursor.contentType,
+				cursor.orderedAt,
+				cursor.contentType,
+				cursor.contentId,
+				limit + 1,
+			)
+	} else {
+		statement = db
+			.prepare(
+				`SELECT * FROM cms_reader_state
+				 WHERE identity_user_id = ? AND site_id = ?
+				 ORDER BY ${orderColumn} DESC, content_type, content_id
+				 LIMIT ?`,
+			)
+			.bind(scope.identityUserId, scope.siteId, limit + 1)
+	}
+	const result = await statement.all<CmsReaderStateRow>()
+	const decoded = (result.results ?? []).map(decodeReaderStateRow)
+	const hasMore = decoded.length > limit
+	const items = hasMore ? decoded.slice(0, limit) : decoded
+	const last = items.at(-1)
+	return {
+		items,
+		nextCursor: hasMore && last ? encodeCursor(last, order) : null,
+	}
+}
+
+export async function exportReaderStatePage(
+	db: D1Database,
+	scope: ReaderStateScope,
+	options: ReaderStateListOptions = {},
+): Promise<ReaderStateExportPage> {
+	const resolvedScope = resolveScope(scope)
+	const page = await readReaderStatePage(db, resolvedScope, options, 'created')
+	return {
+		...page,
+		scope: resolvedScope,
+		exportedAt: Date.now(),
+	}
+}
+
+/**
+ * Consent-withdrawal/privacy clear: remove behavioral history while retaining
+ * explicit read/unread, save, and stated preference choices.
+ */
+export async function clearReaderHistory(db: D1Database, scope: ReaderStateScope): Promise<number> {
+	const resolvedScope = resolveScope(scope)
+	const now = Date.now()
+	const result = await db
+		.prepare(
+			`UPDATE cms_reader_state
+			 SET first_opened_at = NULL, last_opened_at = NULL,
+				 max_progress_bps = 0, media_position_ms = NULL, media_duration_ms = NULL,
+				 progress_observed_at = NULL, automatic_completed_at = NULL,
+				 version = version + 1, updated_at = ?
+			 WHERE identity_user_id = ? AND site_id = ?
+				AND (first_opened_at IS NOT NULL OR last_opened_at IS NOT NULL
+					OR max_progress_bps <> 0 OR media_position_ms IS NOT NULL
+					OR media_duration_ms IS NOT NULL OR progress_observed_at IS NOT NULL
+					OR automatic_completed_at IS NOT NULL)`,
+		)
+		.bind(now, resolvedScope.identityUserId, resolvedScope.siteId)
+		.run()
+	return resultChanges(result)
+}
+
+/** Delete every row for exactly one verified user/site scope. */
+export async function deleteReaderState(db: D1Database, scope: ReaderStateScope): Promise<number> {
+	const resolvedScope = resolveScope(scope)
+	const result = await db
+		.prepare('DELETE FROM cms_reader_state WHERE identity_user_id = ? AND site_id = ?')
+		.bind(resolvedScope.identityUserId, resolvedScope.siteId)
+		.run()
+	return resultChanges(result)
+}
+
+async function executeMutation(
+	db: D1Database,
+	scope: ResolvedScope,
+	key: ContentStateKey,
+	occurredAt: number,
+	expectedVersion: number | undefined,
+	update: ReturnType<D1Database['prepare']>,
+): Promise<ReaderStateMutationResult> {
+	const expected = expectedVersion ?? null
+	const ensure = db
+		.prepare(
+			`INSERT OR IGNORE INTO cms_reader_state
+				(identity_user_id, site_id, content_type, content_id, created_at, updated_at)
+			 SELECT ?, ?, ?, ?, ?, ?
+			 WHERE ? IS NULL OR ? = 0`,
+		)
+		.bind(
+			scope.identityUserId,
+			scope.siteId,
+			key.contentType,
+			key.contentId,
+			occurredAt,
+			occurredAt,
+			expected,
+			expected,
+		)
+	const [, updateResult] = await db.batch([ensure, update])
+	const returnedRow = updateResult?.results?.[0] as CmsReaderStateRow | undefined
+	if (returnedRow) {
+		return { applied: true, reason: 'applied', state: decodeReaderStateRow(returnedRow) }
+	}
+	if (resultChanges(updateResult) > 0) {
+		throw new ReaderStateDurableStateError(
+			'reader state mutation changed a row without returning its atomic state',
+		)
+	}
+	const state = await loadReaderState(db, scope, key)
+	if (!state) {
+		if (expectedVersion !== undefined) {
+			throw new ReaderStateConflictError(expectedVersion, null)
+		}
+		throw new ReaderStateDurableStateError('reader state mutation did not produce a durable row')
+	}
+	if (expectedVersion !== undefined && state.version !== expectedVersion) {
+		throw new ReaderStateConflictError(expectedVersion, state.version)
+	}
+	return { applied: false, reason: 'stale', state }
+}
+
+async function loadReaderState(
+	db: D1Database,
+	scope: ResolvedScope,
+	key: ContentStateKey,
+): Promise<ReaderStateRecord | null> {
+	const row = await db
+		.prepare(
+			`SELECT * FROM cms_reader_state
+			 WHERE identity_user_id = ? AND site_id = ? AND content_type = ? AND content_id = ?`,
+		)
+		.bind(scope.identityUserId, scope.siteId, key.contentType, key.contentId)
+		.first<CmsReaderStateRow>()
+	return row ? decodeReaderStateRow(row) : null
+}
+
+function decodeReaderStateRow(row: CmsReaderStateRow): ReaderStateRecord {
+	let preferences: ReaderPreferences
+	try {
+		preferences = normalizePreferences(JSON.parse(row.preferences_json))
+	} catch (error) {
+		const detail = error instanceof Error ? `: ${error.message}` : ''
+		throw new ReaderStateDurableStateError(`reader state contains unreadable preferences${detail}`)
+	}
+	return {
+		identityUserId: row.identity_user_id,
+		siteId: row.site_id,
+		contentType: row.content_type,
+		contentId: row.content_id,
+		firstOpenedAt: row.first_opened_at,
+		lastOpenedAt: row.last_opened_at,
+		maxProgressBasisPoints: row.max_progress_bps,
+		mediaPositionMs: row.media_position_ms,
+		mediaDurationMs: row.media_duration_ms,
+		progressObservedAt: row.progress_observed_at,
+		automaticCompletedAt: row.automatic_completed_at,
+		manualReadState: row.manual_read_state,
+		manualStateAt: row.manual_state_at,
+		saved: row.saved === 1,
+		savedAt: row.saved_at,
+		preferences,
+		preferencesAt: row.preferences_at,
+		version: row.version,
+		effectiveRead:
+			row.manual_read_state === 'read' ||
+			(row.manual_read_state === null && row.automatic_completed_at !== null),
+		createdAt: row.created_at,
+		updatedAt: row.updated_at,
+	}
+}
+
+function resolveScope(scope: ReaderStateScope): ResolvedScope {
+	if (!scope || typeof scope !== 'object') {
+		throw new ReaderStateInputError('reader state requires a verified scope')
+	}
+	const identityUserId = scope.identityUserId
+	if (
+		typeof identityUserId !== 'string' ||
+		!(UUIDV4_PATTERN.test(identityUserId) || ULID_PATTERN.test(identityUserId))
+	) {
+		throw new ReaderStateInputError(
+			'reader state requires a verified raw realm user id, never an analytics, local, email, or prefixed subject identifier',
+		)
+	}
+	if (typeof scope.siteId !== 'string' || !SITE_ID_PATTERN.test(scope.siteId)) {
+		throw new ReaderStateInputError(
+			'reader state requires a verified stable lowercase site id such as "fronts"',
+		)
+	}
+	return {
+		identityUserId: UUIDV4_PATTERN.test(identityUserId)
+			? identityUserId.toLowerCase()
+			: identityUserId,
+		siteId: scope.siteId,
+	}
+}
+
+function resolveContentKey(key: ContentStateKey): ContentStateKey {
+	if (!key || typeof key !== 'object' || !CONTENT_TYPES.has(key.contentType)) {
+		throw new ReaderStateInputError('reader state requires a supported CMS content type')
+	}
+	if (typeof key.contentId !== 'string' || !CONTENT_ID_PATTERN.test(key.contentId)) {
+		throw new ReaderStateInputError(
+			'reader state requires a stable CMS content id using URL-safe identifier characters',
+		)
+	}
+	return { contentType: key.contentType, contentId: key.contentId }
+}
+
+function resolveBehavioralConsent(options: BehavioralWriteOptions): ReaderBehavioralConsent {
+	if (!options || typeof options !== 'object') {
+		throw new ReaderStateInputError('reader behavioral writes require explicit consent state')
+	}
+	if (options.behavioralConsent !== 'granted' && options.behavioralConsent !== 'denied') {
+		throw new ReaderStateInputError('behavioralConsent must be "granted" or "denied"')
+	}
+	return options.behavioralConsent
+}
+
+function resolveExplicitMutation(options: ExplicitMutationOptions): ResolvedMutation {
+	if (!options || typeof options !== 'object') {
+		throw new ReaderStateInputError('explicit reader state writes require mutation options')
+	}
+	if (typeof options.mutationId !== 'string' || !MUTATION_ID_PATTERN.test(options.mutationId)) {
+		throw new ReaderStateInputError('explicit reader state writes require a stable mutationId')
+	}
+	return resolveMutation(options)
+}
+
+function resolveMutation(options: {
+	occurredAt?: number
+	expectedVersion?: number
+}): ResolvedMutation {
+	const occurredAt = options.occurredAt ?? Date.now()
+	if (!Number.isSafeInteger(occurredAt) || occurredAt < 0) {
+		throw new ReaderStateInputError(
+			'reader state occurredAt must be a non-negative epoch millisecond',
+		)
+	}
+	if (occurredAt > Date.now() + MAX_EVENT_FUTURE_SKEW_MS) {
+		throw new ReaderStateInputError(
+			'reader state occurredAt exceeds the allowed five-minute clock skew',
+		)
+	}
+	if (
+		options.expectedVersion !== undefined &&
+		(!Number.isSafeInteger(options.expectedVersion) || options.expectedVersion < 0)
+	) {
+		throw new ReaderStateInputError('reader state expectedVersion must be a non-negative integer')
+	}
+	return { occurredAt, expectedVersion: options.expectedVersion }
+}
+
+function assertBasisPoints(value: number): number {
+	if (!Number.isInteger(value) || value < 0 || value > 10_000) {
+		throw new ReaderStateInputError('reader progress must be an integer from 0 through 10000')
+	}
+	return value
+}
+
+function optionalNonNegativeInteger(value: number | undefined, name: string): number | undefined {
+	if (value === undefined) return undefined
+	if (!Number.isSafeInteger(value) || value < 0) {
+		throw new ReaderStateInputError(`reader ${name} must be a non-negative integer`)
+	}
+	return value
+}
+
+function normalizePreferences(value: unknown): ReaderPreferences {
+	if (!value || typeof value !== 'object' || Array.isArray(value)) {
+		throw new ReaderStateInputError('reader preferences must be a plain object of stated values')
+	}
+	const prototype = Object.getPrototypeOf(value)
+	if (prototype !== Object.prototype && prototype !== null) {
+		throw new ReaderStateInputError('reader preferences must be a plain object')
+	}
+	const entries = Object.entries(value)
+	if (entries.length > MAX_PREFERENCE_KEYS) {
+		throw new ReaderStateInputError(`reader preferences are limited to ${MAX_PREFERENCE_KEYS} keys`)
+	}
+	const normalized: ReaderPreferences = Object.create(null)
+	for (const [key, preference] of entries.sort(([a], [b]) => a.localeCompare(b))) {
+		if (
+			!PREFERENCE_KEY_PATTERN.test(key) ||
+			['__proto__', 'constructor', 'prototype'].includes(key)
+		) {
+			throw new ReaderStateInputError('reader preference keys must use safe stable identifiers')
+		}
+		if (
+			preference !== null &&
+			typeof preference !== 'string' &&
+			typeof preference !== 'boolean' &&
+			(typeof preference !== 'number' || !Number.isFinite(preference))
+		) {
+			throw new ReaderStateInputError('reader preference values must be finite scalar values')
+		}
+		normalized[key] = preference as ReaderPreferenceValue
+	}
+	if (
+		new TextEncoder().encode(JSON.stringify(normalized)).byteLength > MAX_PREFERENCES_JSON_BYTES
+	) {
+		throw new ReaderStateInputError(
+			`reader preferences are limited to ${MAX_PREFERENCES_JSON_BYTES} encoded bytes`,
+		)
+	}
+	return normalized
+}
+
+function resolveLimit(value: number | undefined): number {
+	const limit = value ?? DEFAULT_READER_STATE_BATCH_SIZE
+	if (!Number.isInteger(limit) || limit < 1 || limit > MAX_READER_STATE_BATCH_SIZE) {
+		throw new ReaderStateInputError(
+			`reader state list limits must be from 1 through ${MAX_READER_STATE_BATCH_SIZE}`,
+		)
+	}
+	return limit
+}
+
+type ReaderStateOrder = 'updated' | 'created'
+
+interface ReaderStateCursor {
+	order: ReaderStateOrder
+	orderedAt: number
+	contentType: ContentType
+	contentId: string
+}
+
+function encodeCursor(record: ReaderStateRecord, order: ReaderStateOrder): string {
+	const orderedAt = order === 'updated' ? record.updatedAt : record.createdAt
+	return encodeURIComponent(
+		JSON.stringify([order, orderedAt, record.contentType, record.contentId]),
+	)
+}
+
+function decodeCursor(cursor: string, expectedOrder: ReaderStateOrder): ReaderStateCursor {
+	try {
+		const parsed = JSON.parse(decodeURIComponent(cursor))
+		if (
+			!Array.isArray(parsed) ||
+			parsed.length !== 4 ||
+			parsed[0] !== expectedOrder ||
+			!Number.isSafeInteger(parsed[1])
+		) {
+			throw new Error('shape')
+		}
+		const key = resolveContentKey({ contentType: parsed[2], contentId: parsed[3] })
+		return { order: expectedOrder, orderedAt: parsed[1], ...key }
+	} catch (error) {
+		if (error instanceof ReaderStateInputError) throw error
+		throw new ReaderStateInputError('reader state cursor is invalid')
+	}
+}
+
+function resultChanges(result: D1Result | undefined): number {
+	const changes = result?.meta?.changes
+	if (typeof changes !== 'number' || !Number.isFinite(changes)) {
+		throw new ReaderStateDurableStateError('reader state mutation returned no finite change count')
+	}
+	return changes
+}