@contember/migrations-client 2.1.0-rc.3 → 2.2.0-alpha.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contember/migrations-client",
-  "version": "2.1.0-rc.3",
+  "version": "2.2.0-alpha.10",
   "license": "Apache-2.0",
   "main": "./dist/production/index.js",
   "typings": "./dist/types/index.d.ts",
@@ -26,11 +26,11 @@
     "test": "echo 'No tests'"
   },
   "dependencies": {
-    "@contember/engine-common": "2.1.0-rc.3",
-    "@contember/graphql-client": "2.1.0-rc.3",
-    "@contember/schema": "2.1.0-rc.3",
-    "@contember/schema-migrations": "2.1.0-rc.3",
-    "@contember/schema-utils": "2.1.0-rc.3"
+    "@contember/engine-common": "2.2.0-alpha.10",
+    "@contember/graphql-client": "2.2.0-alpha.10",
+    "@contember/schema": "2.2.0-alpha.10",
+    "@contember/schema-migrations": "2.2.0-alpha.10",
+    "@contember/schema-utils": "2.2.0-alpha.10"
   },
   "devDependencies": {
     "@types/node": "^24.12.0"

package/src/JsLoader.ts

@@ -1,6 +1,6 @@
-import { MigrationFileLoader } from './MigrationFileLoader'
-import { MigrationParser } from './MigrationParser'
-import { ContentMigration, ContentMigrationFactoryArgs, MigrationContent, MigrationFile } from './MigrationFile'
+import { MigrationFileLoader } from './MigrationFileLoader.js'
+import { MigrationParser } from './MigrationParser.js'
+import { ContentMigration, ContentMigrationFactoryArgs, MigrationContent, MigrationFile } from './MigrationFile.js'
 
 export class JsLoader implements MigrationFileLoader {
 	constructor(

package/src/JsonLoader.ts

@@ -1,7 +1,7 @@
-import { MigrationFileLoader } from './MigrationFileLoader'
+import { MigrationFileLoader } from './MigrationFileLoader.js'
 import * as fs from 'node:fs/promises'
-import { MigrationParser } from './MigrationParser'
-import { MigrationFile } from './MigrationFile'
+import { MigrationParser } from './MigrationParser.js'
+import { MigrationFile } from './MigrationFile.js'
 
 export class JsonLoader implements MigrationFileLoader {
 	constructor(

package/src/MigrationCreator.ts

@@ -1,4 +1,4 @@
-import { MigrationFilesManager } from './MigrationFilesManager'
+import { MigrationFilesManager } from './MigrationFilesManager.js'
 import { Schema } from '@contember/schema'
 import { Migration, SchemaDiffer, VERSION_LATEST } from '@contember/schema-migrations'
 import { MigrationVersionHelper } from '@contember/engine-common'
@@ -25,11 +25,13 @@ export class MigrationCreator {
 		initialSchema: Schema,
 		newSchema: Schema,
 		migrationName: string,
-		{ skipInitialSchemaValidation = false }: { skipInitialSchemaValidation?: boolean } = {},
+		{ skipInitialSchemaValidation = false, skipNonModelDiffers = false, recreateViews = false }: {
+			skipInitialSchemaValidation?: boolean
+			skipNonModelDiffers?: boolean
+			recreateViews?: boolean
+		} = {},
 	): Promise<{ migration: Migration; initialSchema: Schema } | null> {
-		await this.migrationFilesManager.createDirIfNotExist()
-
-		const modifications = this.schemaDiffer.diffSchemas(initialSchema, newSchema, { skipInitialSchemaValidation })
+		const modifications = this.schemaDiffer.diffSchemas(initialSchema, newSchema, { skipInitialSchemaValidation, skipNonModelDiffers, recreateViews })
 		if (modifications.length === 0) {
 			return null
 		}
@@ -40,6 +42,7 @@ export class MigrationCreator {
 	}
 
 	async saveMigration(migration: Migration): Promise<string> {
+		await this.migrationFilesManager.createDirIfNotExist()
 		const jsonDiff = MigrationCreator.createContent(migration)
 		const filename = await this.migrationFilesManager.createFile(jsonDiff, migration.name)
 		return filename

package/src/MigrationExecuteHelper.ts

@@ -1,7 +1,8 @@
-import { MigrationToExecuteOkStatus } from './migrations'
-import { ContentMigrationFactoryArgs, ResolvedMigrationContent } from './MigrationFile'
-import { assertNever } from './utils/assertNever'
-import { SystemClient } from './SystemClient'
+import { MigrationToExecuteOkStatus } from './migrations.js'
+import { ContentMigrationFactoryArgs, ResolvedMigrationContent } from './MigrationFile.js'
+import { assertNever } from './utils/assertNever.js'
+import { SystemClient } from './SystemClient.js'
+import { SchemaState } from './SchemaStateManager.js'
 
 export class MigrationExecutor {
 	async executeMigrations({
@@ -9,6 +10,7 @@ export class MigrationExecutor {
 		migrations,
 		contentMigrationFactoryArgs,
 		force,
+		schemaState,
 		log = () => null,
 	}: {
 		client: SystemClient
@@ -16,14 +18,16 @@ export class MigrationExecutor {
 		contentMigrationFactoryArgs: Omit<ContentMigrationFactoryArgs, 'migration'>
 		log: (message: string) => void
 		force?: boolean
+		schemaState?: SchemaState
 	}): Promise<void> {
-		if (migrations.length === 0) {
+		if (migrations.length === 0 && !schemaState) {
 			return
 		}
 		let migrationsToRun: ResolvedMigrationContent[] = []
+		let batchSchemaState: SchemaState | undefined
 
 		const executeMigrations = async () => {
-			if (migrationsToRun.length === 0) {
+			if (migrationsToRun.length === 0 && !batchSchemaState) {
 				return
 			}
 			await client.migrate(
@@ -51,14 +55,18 @@ export class MigrationExecutor {
 					return assertNever(it)
 				}),
 				force,
+				batchSchemaState,
 			)
 			migrationsToRun.forEach(it => {
 				log(it.name)
 			})
 			migrationsToRun = []
+			batchSchemaState = undefined
 		}
 
-		log('Executing...')
+		if (migrations.length > 0) {
+			log('Executing...')
+		}
 
 		for (const migration of migrations) {
 			const migrationContent = await migration.localMigration.getContent()
@@ -74,7 +82,10 @@ export class MigrationExecutor {
 				migrationsToRun.push(migrationContent)
 			}
 		}
+		batchSchemaState = schemaState
 		await executeMigrations()
-		log('Migration executed')
+		if (migrations.length > 0) {
+			log('Migration executed')
+		}
 	}
 }

package/src/MigrationFile.ts

@@ -1,6 +1,6 @@
 import { Migration } from '@contember/schema-migrations'
-import { JSONObject } from './utils/json'
-import { SchemaVersionBuilder } from './SchemaVersionBuilder'
+import { JSONObject } from './utils/json.js'
+import { SchemaVersionBuilder } from './SchemaVersionBuilder.js'
 
 export interface MigrationFile {
 	path: string

package/src/MigrationFileLoader.ts

@@ -1,4 +1,4 @@
-import { MigrationContent, MigrationFile } from './MigrationFile'
+import { MigrationContent, MigrationFile } from './MigrationFile.js'
 
 export interface MigrationFileLoader {
 	load(file: MigrationFile): Promise<MigrationContent>

package/src/MigrationFilesManager.ts

@@ -1,7 +1,7 @@
 import { MigrationVersionHelper } from '@contember/engine-common'
 import * as fs from 'node:fs/promises'
-import { MigrationFileLoader } from './MigrationFileLoader'
-import { MigrationContent, MigrationFile } from './MigrationFile'
+import { MigrationFileLoader } from './MigrationFileLoader.js'
+import { MigrationContent, MigrationFile } from './MigrationFile.js'
 import { join } from 'node:path'
 import { Dirent } from 'node:fs'
 

package/src/MigrationParser.ts

@@ -1,6 +1,6 @@
 import { Migration, VERSION_INITIAL } from '@contember/schema-migrations'
-import { ContentMigrationQuery, MigrationFile, ResolvedMigrationContent } from './MigrationFile'
-import { JSONValue } from './utils/json'
+import { ContentMigrationQuery, MigrationFile, ResolvedMigrationContent } from './MigrationFile.js'
+import { JSONValue } from './utils/json.js'
 
 export class MigrationParser {
 	public parse(migrationFile: MigrationFile, content: JSONValue): ResolvedMigrationContent {

package/src/MigrationsResolver.ts

@@ -1,6 +1,6 @@
-import { MigrationFilesManager } from './MigrationFilesManager'
+import { MigrationFilesManager } from './MigrationFilesManager.js'
 import { Migration } from '@contember/schema-migrations'
-import { isSchemaMigration, MigrationFile } from './MigrationFile'
+import { isSchemaMigration, MigrationFile } from './MigrationFile.js'
 import { MigrationVersionHelper } from '@contember/engine-common'
 
 export class MigrationsResolver {

package/src/SchemaStateManager.ts

@@ -0,0 +1,75 @@
+import { Acl, Actions, Schema, Settings, Validation } from '@contember/schema'
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+
+export type SchemaState = {
+	acl: Acl.Schema
+	validation: Validation.Schema
+	actions: Actions.Schema
+	settings: Settings.Schema
+}
+
+const stateFiles = ['acl', 'validation', 'actions', 'settings'] as const
+type StateKey = typeof stateFiles[number]
+
+export class SchemaStateManager {
+	constructor(private readonly stateDir: string) {}
+
+	async isStateMode(): Promise<boolean> {
+		try {
+			const stat = await fs.stat(this.stateDir)
+			return stat.isDirectory()
+		} catch {
+			return false
+		}
+	}
+
+	async readState(): Promise<SchemaState> {
+		const state: Partial<SchemaState> = {}
+		for (const key of stateFiles) {
+			const filePath = path.join(this.stateDir, `${key}.json`)
+			try {
+				const content = await fs.readFile(filePath, 'utf8')
+				state[key] = JSON.parse(content)
+			} catch (e) {
+				throw new Error(`Failed to read schema state file ${filePath}: ${e instanceof Error ? e.message : e}`)
+			}
+		}
+		return state as SchemaState
+	}
+
+	async writeState(state: SchemaState, { dryRun = false }: { dryRun?: boolean } = {}): Promise<boolean> {
+		let changed = false
+		for (const key of stateFiles) {
+			const filePath = path.join(this.stateDir, `${key}.json`)
+			const newContent = JSON.stringify(state[key], undefined, '\t') + '\n'
+			let currentContent: string | null = null
+			try {
+				currentContent = await fs.readFile(filePath, 'utf8')
+			} catch {
+				// file doesn't exist yet
+			}
+			if (currentContent !== newContent) {
+				if (!dryRun) {
+					await fs.writeFile(filePath, newContent, 'utf8')
+				}
+				changed = true
+			}
+		}
+		return changed
+	}
+
+	async extractState(schema: Schema): Promise<void> {
+		await fs.mkdir(this.stateDir, { recursive: true })
+		await this.writeState(SchemaStateManager.schemaStateFromSchema(schema))
+	}
+
+	static schemaStateFromSchema(schema: Schema): SchemaState {
+		return {
+			acl: schema.acl,
+			validation: schema.validation,
+			actions: schema.actions,
+			settings: schema.settings,
+		}
+	}
+}

package/src/SchemaVersionBuilder.ts

@@ -1,20 +1,42 @@
 import { Schema } from '@contember/schema'
 import { emptySchema } from '@contember/schema-utils'
-import { SchemaMigrator } from '@contember/schema-migrations'
-import { MigrationsResolver } from './MigrationsResolver'
+import { Migration, SchemaMigrator } from '@contember/schema-migrations'
+import { MigrationsResolver } from './MigrationsResolver.js'
+import { SchemaStateManager } from './SchemaStateManager.js'
 
 export class SchemaVersionBuilder {
+	private lastBuildUntil: { migrations: Migration[]; schema: Schema } | null = null
+
 	constructor(
 		private readonly migrationsResolver: MigrationsResolver,
 		private readonly schemaMigrator: SchemaMigrator,
+		private readonly schemaStateManager: SchemaStateManager,
 	) {}
 
 	async buildSchema(targetVersion?: string): Promise<Schema> {
-		return this.buildSchemaAdvanced(emptySchema, version => !targetVersion || version <= targetVersion)
+		let schema = await this.buildSchemaAdvanced(emptySchema, version => !targetVersion || version <= targetVersion)
+		if (!targetVersion && await this.schemaStateManager.isStateMode()) {
+			const state = await this.schemaStateManager.readState()
+			schema = { ...schema, ...state }
+		}
+		return schema
 	}
 
+	/**
+	 * Content migrations call this once each, with ascending versions. Continuing from the previous
+	 * build keeps a run linear instead of replaying every schema migration from scratch each time.
+	 */
 	async buildSchemaUntil(targetVersion: string): Promise<Schema> {
-		return this.buildSchemaAdvanced(emptySchema, version => version < targetVersion)
+		const migrations = (await this.migrationsResolver.getSchemaMigrations()).filter(({ version }) => version < targetVersion)
+		const previous = this.lastBuildUntil
+		const canContinue = previous !== null
+			&& previous.migrations.length <= migrations.length
+			&& previous.migrations.every((migration, index) => migration === migrations[index])
+		const start = canContinue ? previous : { migrations: [], schema: emptySchema }
+
+		const schema = this.applyMigrations(start.schema, migrations.slice(start.migrations.length))
+		this.lastBuildUntil = { migrations, schema }
+		return schema
 	}
 
 	async continue(schema: Schema, previousVersion: string | null, targetVersion: string): Promise<Schema> {
@@ -22,11 +44,14 @@ export class SchemaVersionBuilder {
 	}
 
 	public async buildSchemaAdvanced(initialSchema: Schema, condition: (version: string) => boolean): Promise<Schema> {
-		return (await this.migrationsResolver.getSchemaMigrations())
-			.filter(({ version }) => condition(version))
-			.reduce<Schema>(
-				(schema, { modifications, formatVersion }) => this.schemaMigrator.applyModifications(schema, modifications, formatVersion),
-				initialSchema,
-			)
+		const migrations = (await this.migrationsResolver.getSchemaMigrations()).filter(({ version }) => condition(version))
+		return this.applyMigrations(initialSchema, migrations)
+	}
+
+	private applyMigrations(initialSchema: Schema, migrations: Migration[]): Schema {
+		return migrations.reduce<Schema>(
+			(schema, { modifications, formatVersion }) => this.schemaMigrator.applyModifications(schema, modifications, formatVersion),
+			initialSchema,
+		)
 	}
 }

package/src/SnapshotManager.ts

@@ -0,0 +1,52 @@
+import { Migration } from '@contember/schema-migrations'
+import * as fs from 'node:fs/promises'
+
+export type CoveredMigration = {
+	version: string
+	name: string
+	type: 'schema' | 'content'
+	/** schema migration checksum, or null for content migrations (mirrors the executed registry) */
+	checksum: string | null
+}
+
+export type SnapshotFile = {
+	/** last covered migration version (X) */
+	version: string
+	/** whether the project used schema state mode when the snapshot was created */
+	stateMode: boolean
+	/** collapsed schema (empty -> X), applied in a single step */
+	snapshot: {
+		formatVersion: number
+		modifications: Migration.Modification[]
+	}
+	/** migrations subsumed by the snapshot, recorded as executed without replaying them */
+	covers: CoveredMigration[]
+	/** versions of content migrations within the covered range whose data is NOT reproduced */
+	contentMigrations: string[]
+}
+
+export class SnapshotManager {
+	constructor(private readonly snapshotPath: string) {}
+
+	async exists(): Promise<boolean> {
+		try {
+			const stat = await fs.stat(this.snapshotPath)
+			return stat.isFile()
+		} catch {
+			return false
+		}
+	}
+
+	async read(): Promise<SnapshotFile> {
+		try {
+			const content = await fs.readFile(this.snapshotPath, 'utf8')
+			return JSON.parse(content) as SnapshotFile
+		} catch (e) {
+			throw new Error(`Failed to read snapshot file ${this.snapshotPath}: ${e instanceof Error ? e.message : e}`)
+		}
+	}
+
+	async write(snapshot: SnapshotFile): Promise<void> {
+		await fs.writeFile(this.snapshotPath, JSON.stringify(snapshot, undefined, '\t') + '\n', 'utf8')
+	}
+}

package/src/SystemClient.ts

@@ -1,5 +1,6 @@
 import { GraphQlClient } from '@contember/graphql-client'
-import { ExecutedMigration, ExecutedMigrationInfo } from './migrations'
+import { ExecutedMigration, ExecutedMigrationInfo } from './migrations.js'
+import { SchemaState } from './SchemaStateManager.js'
 
 export type MigrateError = {
 	readonly code: MigrateErrorCode
@@ -13,6 +14,13 @@ export enum MigrateErrorCode {
 	InvalidFormat = 'INVALID_FORMAT',
 	InvalidSchema = 'INVALID_SCHEMA',
 	MigrationFailed = 'MIGRATION_FAILED',
+	ProjectNotEmpty = 'PROJECT_NOT_EMPTY',
+}
+
+export type SnapshotInput = {
+	formatVersion: number
+	modifications: unknown[]
+	covers: unknown[]
 }
 
 export type MigrateResponse = {
@@ -28,10 +36,10 @@ export class SystemClient {
 		return new SystemClient(graphqlClient)
 	}
 
-	public async migrate(migrations: any[], force = false): Promise<void> {
+	public async migrate(migrations: any[], force = false, schemaState?: SchemaState): Promise<void> {
 		const query = `
-mutation($migrations: [Migration!]!) {
-	migrate: ${force ? 'forceMigrate' : 'migrate'}(migrations: $migrations) {
+mutation($migrations: [Migration!]!, $schemaState: SchemaStateInput) {
+	migrate: ${force ? 'forceMigrate' : 'migrate'}(migrations: $migrations, schemaState: $schemaState) {
 		ok
 		errors {
 			code
@@ -47,6 +55,7 @@ mutation($migrations: [Migration!]!) {
 			}>(query, {
 				variables: {
 					migrations,
+					schemaState: schemaState ?? null,
 				},
 			})
 		).migrate
@@ -55,6 +64,34 @@ mutation($migrations: [Migration!]!) {
 		}
 	}
 
+	public async migrateFromSnapshot(snapshot: SnapshotInput, schemaState?: SchemaState): Promise<void> {
+		const query = `
+mutation($snapshot: SnapshotInput!, $schemaState: SchemaStateInput) {
+	migrateFromSnapshot(snapshot: $snapshot, schemaState: $schemaState) {
+		ok
+		errors {
+			code
+			migration
+			message: developerMessage
+		}
+	}
+}
+`
+		const result = (
+			await this.apiClient.execute<{
+				migrateFromSnapshot: { ok: boolean; errors: { code: MigrateErrorCode; migration: string; message: string }[] }
+			}>(query, {
+				variables: {
+					snapshot,
+					schemaState: schemaState ?? null,
+				},
+			})
+		).migrateFromSnapshot
+		if (!result.ok) {
+			throw result.errors
+		}
+	}
+
 	public async migrationDelete(version: string): Promise<void> {
 		const query = `
 mutation($version: String!) {

package/src/index.ts

@@ -7,15 +7,17 @@ export {
 	VERSION_LATEST,
 } from '@contember/schema-migrations'
 export type { Migration, MigrationInfo } from '@contember/schema-migrations'
-export * from './JsLoader'
-export * from './JsonLoader'
-export * from './MigrationCreator'
-export * from './MigrationExecuteHelper'
-export * from './MigrationFile'
-export * from './MigrationFileLoader'
-export * from './MigrationFilesManager'
-export * from './MigrationParser'
-export * from './migrations'
-export * from './MigrationsResolver'
-export * from './SchemaVersionBuilder'
-export * from './SystemClient'
+export * from './JsLoader.js'
+export * from './JsonLoader.js'
+export * from './MigrationCreator.js'
+export * from './MigrationExecuteHelper.js'
+export * from './MigrationFile.js'
+export * from './MigrationFileLoader.js'
+export * from './MigrationFilesManager.js'
+export * from './MigrationParser.js'
+export * from './migrations.js'
+export * from './MigrationsResolver.js'
+export * from './SchemaStateManager.js'
+export * from './SchemaVersionBuilder.js'
+export * from './SnapshotManager.js'
+export * from './SystemClient.js'

package/src/migrations.ts

@@ -1,5 +1,5 @@
 import { calculateMigrationChecksum, Migration, MigrationInfo } from '@contember/schema-migrations'
-import { isSchemaMigration, MigrationFile } from './MigrationFile'
+import { isSchemaMigration, MigrationFile } from './MigrationFile.js'
 
 export interface ExecutedMigrationInfo extends MigrationInfo {
 	readonly executedAt: Date

package/tests/cases/unit/MigrationCreator.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import * as fs from 'node:fs/promises'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { c, createSchema } from '@contember/schema-definition'
+import { emptySchema } from '@contember/schema-utils'
+import {
+	JsonLoader,
+	MigrationCreator,
+	MigrationFilesManager,
+	MigrationParser,
+	ModificationHandlerFactory,
+	SchemaDiffer,
+	SchemaMigrator,
+} from '../../../src/index.js'
+
+namespace Model {
+	export class Article {
+		title = c.stringColumn()
+	}
+}
+
+let workDir: string
+const exists = (file: string): Promise<boolean> => fs.stat(file).then(() => true, () => false)
+
+beforeEach(async () => {
+	workDir = await fs.mkdtemp(path.join(os.tmpdir(), 'contember-migration-creator-'))
+})
+
+afterEach(async () => {
+	await fs.rm(workDir, { recursive: true, force: true })
+})
+
+test('prepareMigration is filesystem-pure and saveMigration creates the directory', async () => {
+	const migrationsDir = path.join(workDir, 'migrations')
+	const filesManager = new MigrationFilesManager(migrationsDir, { json: new JsonLoader(new MigrationParser()) })
+	const migrator = new SchemaMigrator(new ModificationHandlerFactory(ModificationHandlerFactory.defaultFactoryMap))
+	const creator = new MigrationCreator(filesManager, new SchemaDiffer(migrator))
+
+	const prepared = await creator.prepareMigration(emptySchema, createSchema(Model), 'initial')
+
+	expect(prepared).not.toBeNull()
+	expect(await exists(migrationsDir)).toBe(false)
+	if (prepared === null) {
+		throw new Error('Expected a migration')
+	}
+	const file = await creator.saveMigration(prepared.migration)
+	expect(await exists(migrationsDir)).toBe(true)
+	expect(await exists(file)).toBe(true)
+})

package/tests/cases/unit/SchemaStateManager.test.ts

@@ -0,0 +1,96 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import * as fs from 'node:fs/promises'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { SchemaStateManager } from '../../../src/index.js'
+import { emptySchema } from '@contember/schema-utils'
+import { Schema } from '@contember/schema'
+
+const schemaWithAcl: Schema = {
+	...emptySchema,
+	acl: {
+		roles: {
+			admin: { variables: {}, stages: '*', entities: {} },
+		},
+	},
+	settings: { content: { useExistsInHasManyFilter: true } },
+}
+
+describe('SchemaStateManager', () => {
+	let baseDir: string
+	let stateDir: string
+	let manager: SchemaStateManager
+
+	beforeEach(async () => {
+		baseDir = await fs.mkdtemp(path.join(os.tmpdir(), 'contember-state-'))
+		stateDir = path.join(baseDir, 'state')
+		manager = new SchemaStateManager(stateDir)
+	})
+
+	afterEach(async () => {
+		await fs.rm(baseDir, { recursive: true, force: true })
+	})
+
+	test('isStateMode is false when the state directory does not exist', async () => {
+		expect(await manager.isStateMode()).toBe(false)
+	})
+
+	test('isStateMode is false when the path is a file, not a directory', async () => {
+		await fs.writeFile(stateDir, 'not a dir')
+		expect(await manager.isStateMode()).toBe(false)
+	})
+
+	test('extractState creates the directory and round-trips through readState', async () => {
+		await manager.extractState(schemaWithAcl)
+
+		expect(await manager.isStateMode()).toBe(true)
+
+		const state = await manager.readState()
+		expect(state.acl).toStrictEqual(schemaWithAcl.acl)
+		expect(state.validation).toStrictEqual(schemaWithAcl.validation)
+		expect(state.actions).toStrictEqual(schemaWithAcl.actions)
+		expect(state.settings).toStrictEqual(schemaWithAcl.settings)
+	})
+
+	test('extractState writes one JSON file per state part', async () => {
+		await manager.extractState(schemaWithAcl)
+
+		const files = (await fs.readdir(stateDir)).sort()
+		expect(files).toStrictEqual(['acl.json', 'actions.json', 'settings.json', 'validation.json'])
+	})
+
+	test('writeState in dryRun mode reports a change but does not touch the filesystem', async () => {
+		await fs.mkdir(stateDir, { recursive: true })
+
+		const changed = await manager.writeState(SchemaStateManager.schemaStateFromSchema(schemaWithAcl), { dryRun: true })
+
+		expect(changed).toBe(true)
+		expect(await fs.readdir(stateDir)).toStrictEqual([])
+	})
+
+	test('writeState is idempotent: a second identical write reports no change', async () => {
+		const state = SchemaStateManager.schemaStateFromSchema(schemaWithAcl)
+		await fs.mkdir(stateDir, { recursive: true })
+
+		expect(await manager.writeState(state)).toBe(true)
+		expect(await manager.writeState(state)).toBe(false)
+	})
+
+	test('writeState detects a change when a state part differs', async () => {
+		await manager.extractState(schemaWithAcl)
+
+		const modified = SchemaStateManager.schemaStateFromSchema({
+			...schemaWithAcl,
+			acl: { roles: {} },
+		})
+		expect(await manager.writeState(modified, { dryRun: true })).toBe(true)
+	})
+
+	test('readState throws a descriptive error when a state file is missing', async () => {
+		await fs.mkdir(stateDir, { recursive: true })
+		await fs.writeFile(path.join(stateDir, 'acl.json'), JSON.stringify({ roles: {} }))
+		// validation.json / actions.json / settings.json are missing
+
+		await expect(manager.readState()).rejects.toThrow(/Failed to read schema state file/)
+	})
+})