@growth-labs/cms 0.2.0 → 0.3.1

package/src/index.ts

@@ -1,8 +1,8 @@
 // @growth-labs/cms — the reusable Fronts-proven publishing/admin engine, as a
 // package (NOT a shared engine). See docs/reference/cms-reuse-decision.md.
 //
-// This package ships the D1 schema contract (the 11-table
-// content/revision/media/authors/foundry-callback set) + its TypeScript row
+// This package ships the D1 schema contract (the original 11-table
+// content/revision/media/authors/foundry-callback set plus additive migrations) + its TypeScript row
 // types (WS7-04/06 foundation) AND the publishing engine — the content
 // data-access core (WS7-05):
 //
@@ -50,6 +50,7 @@ export {
 	type CmsActivityLogRow,
 	type CmsApiKeyRow,
 	type CmsNotificationRow,
+	type CmsReaderStateRow,
 	type CmsRole,
 	type CmsTableName,
 	type CmsWebhookRow,
@@ -73,6 +74,7 @@ export {
 	type MediaAssetRow,
 	NON_CMS_TABLES,
 	type PodcastContentRow,
+	type ReaderManualReadState,
 	splitStatements,
 	type VideoContentRow,
 	type VideoProcessingState,

package/src/migration-vendor-files.ts

@@ -0,0 +1,100 @@
+import { link, unlink } from 'node:fs/promises'
+
+export interface StagedMigrationVendorFile {
+	tempPath: string
+	targetPath: string
+}
+
+export interface MigrationVendorFileOperations {
+	link(source: string, target: string): Promise<void>
+	unlink(path: string): Promise<void>
+}
+
+const DEFAULT_OPERATIONS: MigrationVendorFileOperations = { link, unlink }
+
+async function removePaths(
+	paths: string[],
+	operations: MigrationVendorFileOperations,
+): Promise<unknown[]> {
+	const errors: unknown[] = []
+	for (const path of [...paths].reverse()) {
+		try {
+			await operations.unlink(path)
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== 'ENOENT') errors.push(error)
+		}
+	}
+	return errors
+}
+
+export async function rollbackNewFiles(
+	paths: string[],
+	operations: MigrationVendorFileOperations = DEFAULT_OPERATIONS,
+): Promise<void> {
+	const errors = await removePaths(paths, operations)
+	if (errors.length > 0) {
+		throw new AggregateError(errors, 'failed to roll back newly linked CMS migration files')
+	}
+}
+
+/**
+ * Link every pre-staged file without replacing an existing directory entry.
+ * A later failure removes all targets linked by this attempt and every temp.
+ */
+export async function commitNewFilesAtomically(
+	files: StagedMigrationVendorFile[],
+	operations: MigrationVendorFileOperations = DEFAULT_OPERATIONS,
+): Promise<string[]> {
+	const committed: string[] = []
+	let failure: unknown
+
+	try {
+		for (const file of files) {
+			await operations.link(file.tempPath, file.targetPath)
+			committed.push(file.targetPath)
+		}
+	} catch (error) {
+		failure = error
+	}
+
+	const cleanupErrors = await removePaths(
+		files.map((file) => file.tempPath),
+		operations,
+	)
+	if (failure) {
+		const rollbackErrors = await removePaths(committed, operations)
+		const errors = [failure, ...cleanupErrors, ...rollbackErrors].filter(
+			(error): error is NonNullable<unknown> => error !== undefined,
+		)
+		const primary = failure instanceof Error ? `: ${failure.message}` : ''
+		throw new AggregateError(errors, `CMS migration file commit failed${primary}`)
+	}
+	// A hard-linked target remains valid when unlinking only its staged temp
+	// fails. The caller's outer finally retries temp cleanup; rolling targets
+	// back here would turn a harmless leftover temp into data loss.
+
+	return committed
+}
+
+/** Commit staged SQL, then run the receipt/final verification boundary. */
+export async function commitStagedMigrationBatch(
+	files: StagedMigrationVendorFile[],
+	finalize: () => Promise<void>,
+	operations: MigrationVendorFileOperations = DEFAULT_OPERATIONS,
+): Promise<string[]> {
+	const committed = await commitNewFilesAtomically(files, operations)
+	try {
+		await finalize()
+		return committed
+	} catch (error) {
+		try {
+			await rollbackNewFiles(committed, operations)
+		} catch (rollbackError) {
+			throw new AggregateError(
+				[error, rollbackError],
+				'CMS migration batch finalization failed and rollback was incomplete',
+			)
+		}
+		throw error
+	}
+}

package/src/migration-vendor.ts

@@ -0,0 +1,450 @@
+import {
+	link,
+	lstat,
+	readdir,
+	readFile,
+	realpath,
+	rename,
+	unlink,
+	writeFile,
+} from 'node:fs/promises'
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+	commitStagedMigrationBatch,
+	type StagedMigrationVendorFile,
+} from './migration-vendor-files.js'
+
+const PACKAGE_NAME = '@growth-labs/cms'
+const MANIFEST_NAME = '.growth-labs-cms-migrations.json'
+const MANIFEST_SCHEMA_VERSION = 1
+const MIGRATION_FILE = /^\d{4}_[a-z0-9][a-z0-9_-]*\.sql$/
+
+interface PackageJson {
+	name?: string
+	version?: string
+}
+
+interface PlannedMigration {
+	source: string
+	target: string
+	sequence: number
+	sha256: string
+	bytes: Uint8Array
+}
+
+interface CmsMigrationManifestEntry {
+	source: string
+	target: string
+	sha256: string
+}
+
+interface CmsMigrationManifest {
+	schemaVersion: 1
+	packageName: typeof PACKAGE_NAME
+	packageVersion: string
+	startSequence: number
+	files: CmsMigrationManifestEntry[]
+}
+
+export interface SyncCmsMigrationsOptions {
+	/** Existing consumer-owned Wrangler migrations directory. */
+	migrationsDir: string
+	/** First unused sequence number reserved for the package migrations. */
+	startSequence: number
+	/** Override only when a consumer keeps the receipt outside migrationsDir. */
+	manifestPath?: string
+}
+
+export interface VerifyCmsMigrationsOptions {
+	migrationsDir: string
+	manifestPath?: string
+}
+
+export interface CmsMigrationVendorResult {
+	packageName: typeof PACKAGE_NAME
+	packageVersion: string
+	startSequence: number
+	managedFiles: string[]
+	written: number
+	verified: number
+	manifestPath: string
+}
+
+interface PackageContract {
+	packageVersion: string
+	sourceDir: string
+}
+
+async function packageContract(): Promise<PackageContract> {
+	const packageRoot = fileURLToPath(new URL('..', import.meta.url))
+	const packageJsonPath = join(packageRoot, 'package.json')
+	const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8')) as PackageJson
+	if (packageJson.name !== PACKAGE_NAME || !packageJson.version) {
+		throw new Error('installed CMS package metadata is invalid')
+	}
+	return {
+		packageVersion: packageJson.version,
+		sourceDir: join(packageRoot, 'migrations'),
+	}
+}
+
+async function sha256(bytes: Uint8Array): Promise<string> {
+	const input = new Uint8Array(bytes.byteLength)
+	input.set(bytes)
+	const digest = await crypto.subtle.digest('SHA-256', input.buffer)
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+async function requireExistingDirectory(path: string, label = 'migrationsDir'): Promise<string> {
+	let stat: Awaited<ReturnType<typeof lstat>>
+	try {
+		stat = await lstat(path)
+	} catch {
+		throw new Error(`${label} must be an existing directory: ${path}`)
+	}
+	if (!stat.isDirectory() || stat.isSymbolicLink()) {
+		throw new Error(`${label} must be an existing non-symlink directory: ${path}`)
+	}
+	return realpath(path)
+}
+
+function assertStartSequence(value: number): void {
+	if (!Number.isSafeInteger(value) || value < 1) {
+		throw new Error('startSequence must be a positive integer')
+	}
+}
+
+function sequencePrefix(sequence: number): string {
+	return String(sequence).padStart(4, '0')
+}
+
+async function planMigrations(
+	sourceDir: string,
+	startSequence: number,
+): Promise<PlannedMigration[]> {
+	assertStartSequence(startSequence)
+	const sourceNames = (await readdir(sourceDir)).filter((name) => MIGRATION_FILE.test(name)).sort()
+	if (sourceNames.length === 0) throw new Error('installed CMS package has no migration SQL')
+	if (startSequence + sourceNames.length - 1 > 9999) {
+		throw new Error('reserved CMS migration sequence exceeds 9999')
+	}
+
+	return Promise.all(
+		sourceNames.map(async (source, index) => {
+			const sequence = startSequence + index
+			const suffix = source.replace(/^\d{4}_/, '')
+			const target = `${sequencePrefix(sequence)}_growth_labs_cms_${suffix}`
+			const bytes = new Uint8Array(await readFile(join(sourceDir, source)))
+			return { source, target, sequence, sha256: await sha256(bytes), bytes }
+		}),
+	)
+}
+
+function manifestFor(
+	packageVersion: string,
+	startSequence: number,
+	plan: PlannedMigration[],
+): CmsMigrationManifest {
+	return {
+		schemaVersion: MANIFEST_SCHEMA_VERSION,
+		packageName: PACKAGE_NAME,
+		packageVersion,
+		startSequence,
+		files: plan.map(({ source, target, sha256: hash }) => ({ source, target, sha256: hash })),
+	}
+}
+
+async function readManifest(path: string): Promise<CmsMigrationManifest | null> {
+	try {
+		const stat = await lstat(path)
+		if (!stat.isFile() || stat.isSymbolicLink()) {
+			throw new Error(`CMS migration manifest must be a regular file: ${path}`)
+		}
+		const parsed = JSON.parse(await readFile(path, 'utf8')) as Partial<CmsMigrationManifest>
+		if (
+			parsed.schemaVersion !== MANIFEST_SCHEMA_VERSION ||
+			parsed.packageName !== PACKAGE_NAME ||
+			!parsed.packageVersion ||
+			!Number.isSafeInteger(parsed.startSequence) ||
+			(parsed.startSequence as number) < 1 ||
+			!Array.isArray(parsed.files)
+		) {
+			throw new Error(`CMS migration manifest is invalid: ${path}`)
+		}
+		for (const entry of parsed.files) {
+			if (
+				!entry ||
+				typeof entry.source !== 'string' ||
+				typeof entry.target !== 'string' ||
+				!MIGRATION_FILE.test(entry.source) ||
+				!MIGRATION_FILE.test(entry.target) ||
+				!/^([a-f0-9]{64})$/.test(entry.sha256)
+			) {
+				throw new Error(`CMS migration manifest contains an invalid file entry: ${path}`)
+			}
+		}
+		return parsed as CmsMigrationManifest
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
+		throw error
+	}
+}
+
+function entriesEqual(left: CmsMigrationManifestEntry, right: CmsMigrationManifestEntry): boolean {
+	return (
+		left.source === right.source && left.target === right.target && left.sha256 === right.sha256
+	)
+}
+
+function assertManifestCanAdvance(
+	current: CmsMigrationManifest | null,
+	next: CmsMigrationManifest,
+): void {
+	if (!current) return
+	if (current.startSequence !== next.startSequence) {
+		throw new Error(
+			`CMS migration manifest reserves startSequence ${current.startSequence}; received ${next.startSequence}`,
+		)
+	}
+	if (current.files.length > next.files.length) {
+		throw new Error('installed CMS package removed migrations recorded by the consumer manifest')
+	}
+	for (const [index, entry] of current.files.entries()) {
+		const nextEntry = next.files[index]
+		if (!nextEntry || !entriesEqual(entry, nextEntry)) {
+			throw new Error(`installed CMS migration changed after vendoring: ${entry.source}`)
+		}
+	}
+}
+
+async function assertNoSequenceCollisions(
+	migrationsDir: string,
+	plan: PlannedMigration[],
+): Promise<void> {
+	const existing = await readdir(migrationsDir)
+	for (const migration of plan) {
+		const prefix = `${sequencePrefix(migration.sequence)}_`
+		const collisions = existing.filter(
+			(name) => name.endsWith('.sql') && name.startsWith(prefix) && name !== migration.target,
+		)
+		if (collisions.length > 0) {
+			throw new Error(
+				`reserved sequence ${sequencePrefix(migration.sequence)} collides with ${collisions.join(', ')}`,
+			)
+		}
+	}
+}
+
+async function verifyTargets(
+	migrationsDir: string,
+	plan: PlannedMigration[],
+	allowMissing: boolean,
+): Promise<{ verified: number; missing: PlannedMigration[] }> {
+	let verified = 0
+	const missing: PlannedMigration[] = []
+	for (const migration of plan) {
+		const targetPath = join(migrationsDir, migration.target)
+		try {
+			const stat = await lstat(targetPath)
+			if (!stat.isFile() || stat.isSymbolicLink()) {
+				throw new Error(`managed CMS migration must be a regular file: ${migration.target}`)
+			}
+			const targetHash = await sha256(new Uint8Array(await readFile(targetPath)))
+			if (targetHash !== migration.sha256) {
+				throw new Error(`CMS migration hash mismatch: ${migration.target}`)
+			}
+			verified += 1
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT' && allowMissing) {
+				missing.push(migration)
+				continue
+			}
+			throw error
+		}
+	}
+	return { verified, missing }
+}
+
+async function stageNewFile(path: string, bytes: Uint8Array): Promise<string> {
+	const temp = `${path}.tmp-${crypto.randomUUID()}`
+	await writeFile(temp, bytes, { flag: 'wx' })
+	return temp
+}
+
+async function stageManifest(path: string, manifest: CmsMigrationManifest): Promise<string> {
+	const temp = `${path}.tmp-${crypto.randomUUID()}`
+	await writeFile(temp, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' })
+	return temp
+}
+
+async function commitManifest(
+	tempPath: string,
+	manifestPath: string,
+	currentManifest: CmsMigrationManifest | null,
+): Promise<void> {
+	if (currentManifest) {
+		const latest = await readManifest(manifestPath)
+		if (!latest || JSON.stringify(latest) !== JSON.stringify(currentManifest)) {
+			throw new Error('CMS migration manifest changed during sync')
+		}
+		await rename(tempPath, manifestPath)
+		return
+	}
+	await link(tempPath, manifestPath)
+}
+
+function isInsideDirectory(directory: string, path: string): boolean {
+	const fromDirectory = relative(directory, path)
+	return (
+		fromDirectory === '' ||
+		(!fromDirectory.startsWith(`..${sep}`) && fromDirectory !== '..' && !isAbsolute(fromDirectory))
+	)
+}
+
+async function resolveManifestPath(migrationsDir: string, override?: string): Promise<string> {
+	if (!override) return join(migrationsDir, MANIFEST_NAME)
+	const requested = resolve(override)
+	if (extname(requested).toLowerCase() !== '.json') {
+		throw new Error('CMS migration manifest override must be a .json file')
+	}
+	if (isInsideDirectory(migrationsDir, requested)) {
+		throw new Error('CMS migration manifest override must be outside migrationsDir')
+	}
+	const parent = await requireExistingDirectory(dirname(requested), 'manifest parent')
+	const resolvedPath = join(parent, basename(requested))
+	if (isInsideDirectory(migrationsDir, resolvedPath)) {
+		throw new Error('CMS migration manifest override must be outside migrationsDir')
+	}
+	return resolvedPath
+}
+
+async function withManifestLock<T>(manifestPath: string, action: () => Promise<T>): Promise<T> {
+	const lockPath = `${manifestPath}.lock`
+	try {
+		await writeFile(lockPath, `${JSON.stringify({ pid: process.pid, startedAt: Date.now() })}\n`, {
+			flag: 'wx',
+			mode: 0o600,
+		})
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+			throw new Error(`another CMS migration operation is already active: ${lockPath}`)
+		}
+		throw error
+	}
+
+	let result: T | undefined
+	let operationError: unknown
+	try {
+		result = await action()
+	} catch (error) {
+		operationError = error
+	}
+	let releaseError: unknown
+	try {
+		await unlink(lockPath)
+	} catch (error) {
+		releaseError = error
+	}
+	if (operationError && releaseError) {
+		throw new AggregateError(
+			[operationError, releaseError],
+			'CMS migration operation failed and its receipt lock could not be released',
+		)
+	}
+	if (operationError) throw operationError
+	if (releaseError) throw releaseError
+	return result as T
+}
+
+export async function syncCmsMigrations(
+	options: SyncCmsMigrationsOptions,
+): Promise<CmsMigrationVendorResult> {
+	assertStartSequence(options.startSequence)
+	const migrationsDir = await requireExistingDirectory(resolve(options.migrationsDir))
+	const manifestPath = await resolveManifestPath(migrationsDir, options.manifestPath)
+	return withManifestLock(manifestPath, async () => {
+		const contract = await packageContract()
+		const plan = await planMigrations(contract.sourceDir, options.startSequence)
+		const nextManifest = manifestFor(contract.packageVersion, options.startSequence, plan)
+		const currentManifest = await readManifest(manifestPath)
+		assertManifestCanAdvance(currentManifest, nextManifest)
+		await assertNoSequenceCollisions(migrationsDir, plan)
+		const preflight = await verifyTargets(migrationsDir, plan, true)
+		const staged: StagedMigrationVendorFile[] = []
+		let manifestTemp: string | null = null
+		let verified = 0
+
+		try {
+			for (const migration of preflight.missing) {
+				const targetPath = join(migrationsDir, migration.target)
+				staged.push({
+					targetPath,
+					tempPath: await stageNewFile(targetPath, migration.bytes),
+				})
+			}
+			const stagedManifest = await stageManifest(manifestPath, nextManifest)
+			manifestTemp = stagedManifest
+			await commitStagedMigrationBatch(staged, async () => {
+				await assertNoSequenceCollisions(migrationsDir, plan)
+				const final = await verifyTargets(migrationsDir, plan, false)
+				verified = final.verified
+				await commitManifest(stagedManifest, manifestPath, currentManifest)
+			})
+
+			return {
+				packageName: PACKAGE_NAME,
+				packageVersion: contract.packageVersion,
+				startSequence: options.startSequence,
+				managedFiles: plan.map(({ target }) => target),
+				written: preflight.missing.length,
+				verified,
+				manifestPath,
+			}
+		} finally {
+			await Promise.all([
+				...staged.map(({ tempPath }) => unlink(tempPath).catch(() => {})),
+				...(manifestTemp ? [unlink(manifestTemp).catch(() => {})] : []),
+			])
+		}
+	})
+}
+
+export async function verifyCmsMigrations(
+	options: VerifyCmsMigrationsOptions,
+): Promise<CmsMigrationVendorResult> {
+	const migrationsDir = await requireExistingDirectory(resolve(options.migrationsDir))
+	const manifestPath = await resolveManifestPath(migrationsDir, options.manifestPath)
+	return withManifestLock(manifestPath, async () => {
+		const manifest = await readManifest(manifestPath)
+		if (!manifest) throw new Error(`CMS migration manifest is missing: ${manifestPath}`)
+		const contract = await packageContract()
+		if (manifest.packageVersion !== contract.packageVersion) {
+			throw new Error(
+				`CMS migration manifest version ${manifest.packageVersion} does not match installed ${contract.packageVersion}`,
+			)
+		}
+		const plan = await planMigrations(contract.sourceDir, manifest.startSequence)
+		const expected = manifestFor(contract.packageVersion, manifest.startSequence, plan)
+		if (
+			expected.files.length !== manifest.files.length ||
+			expected.files.some(
+				(entry, index) => !entriesEqual(entry, manifest.files[index] as CmsMigrationManifestEntry),
+			)
+		) {
+			throw new Error('CMS migration manifest does not match the installed package contract')
+		}
+		await assertNoSequenceCollisions(migrationsDir, plan)
+		const result = await verifyTargets(migrationsDir, plan, false)
+
+		return {
+			packageName: PACKAGE_NAME,
+			packageVersion: contract.packageVersion,
+			startSequence: manifest.startSequence,
+			managedFiles: plan.map(({ target }) => target),
+			written: 0,
+			verified: result.verified,
+			manifestPath,
+		}
+	})
+}

package/src/schema/index.ts

@@ -20,6 +20,7 @@ export type {
 	CmsActivityLogRow,
 	CmsApiKeyRow,
 	CmsNotificationRow,
+	CmsReaderStateRow,
 	CmsRole,
 	CmsWebhookRow,
 	ContentContributorRow,
@@ -40,6 +41,7 @@ export type {
 	MastheadUserRow,
 	MediaAssetRow,
 	PodcastContentRow,
+	ReaderManualReadState,
 	VideoContentRow,
 	VideoProcessingState,
 	WorkspaceInviteRow,

package/src/schema/migrations.ts

@@ -741,6 +741,43 @@ CREATE INDEX idx_content_publication_attempts_recovery
   ON content_publication_attempts(state, updated_at);
 CREATE INDEX idx_content_publication_attempts_content
   ON content_publication_attempts(content_id, created_at DESC);
+`,
+	},
+	{
+		id: '0019_reader_state',
+		sql: `
+CREATE TABLE cms_reader_state (
+  identity_user_id TEXT NOT NULL,
+  site_id TEXT NOT NULL,
+  content_type TEXT NOT NULL CHECK (content_type IN ('article','video','podcast','newsletter','page')),
+  content_id TEXT NOT NULL,
+  first_opened_at INTEGER,
+  last_opened_at INTEGER,
+  max_progress_bps INTEGER NOT NULL DEFAULT 0 CHECK (max_progress_bps BETWEEN 0 AND 10000),
+  media_position_ms INTEGER CHECK (media_position_ms IS NULL OR media_position_ms >= 0),
+  media_duration_ms INTEGER CHECK (media_duration_ms IS NULL OR media_duration_ms >= 0),
+  progress_observed_at INTEGER,
+  automatic_completed_at INTEGER,
+  manual_read_state TEXT CHECK (manual_read_state IS NULL OR manual_read_state IN ('read','unread')),
+  manual_state_at INTEGER,
+  manual_mutation_id TEXT,
+  saved INTEGER NOT NULL DEFAULT 0 CHECK (saved IN (0,1)),
+  saved_at INTEGER,
+  saved_mutation_id TEXT,
+  preferences_json TEXT NOT NULL DEFAULT '{}',
+  preferences_at INTEGER,
+  preferences_mutation_id TEXT,
+  version INTEGER NOT NULL DEFAULT 0 CHECK (version >= 0),
+  created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
+  PRIMARY KEY (identity_user_id, site_id, content_type, content_id)
+);
+CREATE INDEX idx_cms_reader_state_library
+  ON cms_reader_state(identity_user_id, site_id, updated_at DESC, content_type, content_id);
+CREATE INDEX idx_cms_reader_state_export
+  ON cms_reader_state(identity_user_id, site_id, created_at DESC, content_type, content_id);
+CREATE INDEX idx_cms_reader_state_saved
+  ON cms_reader_state(identity_user_id, site_id, saved, updated_at DESC);
 `,
 	},
 ]

package/src/schema/tables.ts

@@ -1,5 +1,7 @@
-// The 11-table content/revision/media/authors/foundry-callback contract that
-// `@growth-labs/cms` owns. Verified against prod `fronts-data` 2026-05-29.
+// The content/revision/media/authors/foundry-callback contract plus additive
+// package-owned CMS platform/product tables. The original 11-table core was
+// verified against prod `fronts-data` 2026-05-29; later entries are versioned
+// migrations with their own workerd contract tests.
 //
 // This list is the CMS boundary made executable: it is exactly the tables the
 // package migration creates and nothing else. Identity/entitlement tables
@@ -23,6 +25,7 @@ export const CMS_TABLES = [
 	'content_contributors',
 	'content_slug_redirects',
 	'content_publication_attempts',
+	'cms_reader_state',
 	// Masthead platform tables (migrations 0008–0011)
 	'workspace_settings',
 	'masthead_users',

package/src/schema/types.ts

@@ -567,6 +567,35 @@ export interface ContentPublicationAttemptRow {
 	updated_at: number
 }
 
+export type ReaderManualReadState = 'read' | 'unread'
+
+/** Package-owned reader product state from migration 0019. */
+export interface CmsReaderStateRow {
+	identity_user_id: string
+	site_id: string
+	content_type: ContentType
+	content_id: string
+	first_opened_at: number | null
+	last_opened_at: number | null
+	max_progress_bps: number
+	media_position_ms: number | null
+	media_duration_ms: number | null
+	progress_observed_at: number | null
+	automatic_completed_at: number | null
+	manual_read_state: ReaderManualReadState | null
+	manual_state_at: number | null
+	manual_mutation_id: string | null
+	saved: number
+	saved_at: number | null
+	saved_mutation_id: string | null
+	preferences_json: string
+	preferences_at: number | null
+	preferences_mutation_id: string | null
+	version: number
+	created_at: number
+	updated_at: number
+}
+
 /**
  * Schema version for the intent_key derivation. Bump ONLY on a breaking change
  * to the canonical-cluster-id semantics; bumping rotates every intent_key (and