@db3.ai/app 0.1.0-beta.1

package/src/db/dialects/postgres.ts

@@ -0,0 +1,143 @@
+import type { Knex } from 'knex';
+import type {
+	DatabaseDialect,
+	TableIndexSpec,
+} from './types';
+import { postgresColumnTypes } from './columnTypes';
+import { vectorFromDbValue } from './mysql';
+
+const VECTOR_MAX_DIMENSIONS = 16000;
+
+/**
+ * PostgreSQL dialect placeholder for pg/pgvector-backed applications.
+ */
+export const postgresDialect: DatabaseDialect = {
+	name: 'postgres',
+	knexClient: 'pg',
+	defaultPort: 5432,
+	supportsReturningRows: true,
+	supportsTableComments: false,
+	supportsVectorIndexes: false,
+	vectorMaxDimensions: VECTOR_MAX_DIMENSIONS,
+	columnTypes: postgresColumnTypes,
+	vectorColumnType,
+	vectorToDbValue,
+	vectorFromDbValue,
+	createDatabase,
+	dropDatabase,
+	quoteIdentifier,
+	getTableIndexes,
+	getTableComments,
+};
+
+/**
+ * Returns the pgvector column type for configured dimensions.
+ */
+function vectorColumnType(dimensions?: number): string {
+	return dimensions === undefined ? 'vector' : `vector(${dimensions})`;
+}
+
+/**
+ * Converts app-memory vectors into pgvector text input.
+ */
+function vectorToDbValue(vector: readonly number[]): string {
+	for (let index = 0; index < vector.length; index += 1) {
+		const value = vector[index];
+
+		if (typeof value !== 'number' || !Number.isFinite(value)) {
+			throw new Error(`Vector value at index ${index} must be a finite number.`);
+		}
+	}
+
+	return JSON.stringify(vector);
+}
+
+/**
+ * Creates a PostgreSQL database for isolated integration tests.
+ */
+async function createDatabase(
+	db: Knex,
+	databaseName: string,
+): Promise<void> {
+	await db.raw(`CREATE DATABASE ${quoteIdentifier(databaseName)}`);
+}
+
+/**
+ * Drops an isolated PostgreSQL integration-test database.
+ */
+async function dropDatabase(
+	db: Knex,
+	databaseName: string,
+): Promise<void> {
+	await db.raw(`DROP DATABASE IF EXISTS ${quoteIdentifier(databaseName)}`);
+}
+
+/**
+ * Quotes a PostgreSQL identifier after the caller has validated its shape.
+ */
+function quoteIdentifier(identifier: string): string {
+	return `"${identifier.replace(/"/g, '""')}"`;
+}
+
+/**
+ * Returns no table comments because PostgreSQL comment sync is not enabled.
+ *
+ * @param _db - Unused database connection.
+ * @param _tableNames - Unused table names.
+ * @returns Empty comment map.
+ */
+async function getTableComments(
+	_db: Knex,
+	_tableNames: string[],
+): Promise<Map<string, string | null>> {
+	return new Map();
+}
+
+/**
+ * Reads PostgreSQL index metadata and normalizes it for schema diffing.
+ */
+async function getTableIndexes(
+	db: Knex,
+	tableName: string,
+): Promise<TableIndexSpec[]> {
+	const rows = await db
+		.select<{
+			index_name: string;
+			column_name: string;
+			column_order: number;
+			is_unique: boolean;
+			is_primary: boolean;
+		}[]>([
+			db.raw('i.relname AS index_name'),
+			db.raw('a.attname AS column_name'),
+			db.raw('array_position(ix.indkey, a.attnum) AS column_order'),
+			db.raw('ix.indisunique AS is_unique'),
+			db.raw('ix.indisprimary AS is_primary'),
+		])
+		.from({ t: 'pg_class' })
+		.join({ n: 'pg_namespace' }, 'n.oid', 't.relnamespace')
+		.join({ ix: 'pg_index' }, 'ix.indrelid', 't.oid')
+		.join({ i: 'pg_class' }, 'i.oid', 'ix.indexrelid')
+		.joinRaw('JOIN pg_attribute AS a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)')
+		.where('t.relname', tableName)
+		.where('n.nspname', 'public')
+		.orderBy('i.relname')
+		.orderBy('column_order');
+	const indexes = new Map<string, TableIndexSpec>();
+
+	for (const row of rows) {
+		const index = indexes.get(row.index_name) ?? {
+			name: row.index_name,
+			columns: [],
+			unique: Boolean(row.is_unique),
+			primary: Boolean(row.is_primary),
+		};
+
+		index.columns.push({
+			name: row.column_name,
+		});
+		indexes.set(row.index_name, index);
+	}
+
+	return [...indexes.values()];
+}

package/src/db/dialects/resolveDialect.ts

@@ -0,0 +1,88 @@
+import type { Knex } from 'knex';
+import { mariaDbDialect } from './mariadb';
+import { mysqlDialect } from './mysql';
+import { postgresDialect } from './postgres';
+import type {
+	DatabaseConnectionName,
+	DatabaseDialect,
+} from './types';
+
+const dialectByConnectionName: Record<DatabaseConnectionName, DatabaseDialect> = {
+	mysql: mysqlDialect,
+	mysql2: mysqlDialect,
+	mariadb: mariaDbDialect,
+	postgres: postgresDialect,
+	pgsql: postgresDialect,
+	pg: postgresDialect,
+};
+
+const dialectByConnection = new WeakMap<Knex, DatabaseDialect>();
+
+/**
+ * Resolves a configured database connection name to a framework dialect.
+ */
+export function resolveDatabaseDialect(
+	connectionName = process.env.DB_CONNECTION || 'mysql2',
+): DatabaseDialect {
+	const normalized = connectionName.trim().toLowerCase() as DatabaseConnectionName;
+	const dialect = dialectByConnectionName[normalized];
+
+	if (!dialect) {
+		throw new Error(
+			`Unsupported DB_CONNECTION "${connectionName}". Use mysql, mysql2, mariadb, postgres, or pg.`,
+		);
+	}
+
+	return dialect;
+}
+
+/**
+ * Associates a Knex connection with the framework dialect that created it.
+ */
+export function rememberDatabaseDialect(
+	connection: Knex,
+	dialect: DatabaseDialect,
+): void {
+	dialectByConnection.set(connection, dialect);
+}
+
+/**
+ * Resolves the best-known dialect for an existing Knex connection.
+ */
+export function databaseDialectForConnection(connection: Knex): DatabaseDialect {
+	const remembered = dialectByConnection.get(connection);
+
+	if (remembered) return remembered;
+
+	const configured = resolveDatabaseDialect();
+	const clientName = databaseClientName(connection);
+
+	if (clientName === configured.knexClient) {
+		return configured;
+	}
+
+	if (clientName === 'mysql' || clientName === 'mysql2') {
+		return mysqlDialect;
+	}
+
+	if (clientName === 'pg' || clientName === 'postgres') {
+		return postgresDialect;
+	}
+
+	return configured;
+}
+
+/**
+ * Extracts Knex's low-level client name from a connection.
+ */
+function databaseClientName(connection: Knex): string {
+	const client = connection.client as {
+		config?: {
+			client?: unknown;
+		};
+		dialect?: unknown;
+	};
+	const name = client.config?.client ?? client.dialect ?? '';
+
+	return String(name).toLowerCase();
+}

package/src/db/dialects/types.ts

@@ -0,0 +1,59 @@
+import type { Knex } from 'knex';
+import type { DatabaseColumnTypes } from './columnTypes';
+
+export type DatabaseDialectName = 'mysql' | 'mariadb' | 'postgres';
+
+export type DatabaseConnectionName =
+	| 'mysql'
+	| 'mysql2'
+	| 'mariadb'
+	| 'postgres'
+	| 'pgsql'
+	| 'pg';
+
+export interface NormalizedIndexColumn {
+	name: string;
+	order?: 'asc' | 'desc';
+}
+
+export interface TableIndexSpec {
+	name: string;
+	columns: NormalizedIndexColumn[];
+	unique: boolean;
+	primary: boolean;
+	type?: 'normal' | 'vector';
+}
+
+export interface DatabaseDialect {
+	name: DatabaseDialectName;
+	knexClient: string;
+	defaultPort: number;
+	supportsReturningRows: boolean;
+	supportsTableComments: boolean;
+	supportsVectorIndexes: boolean;
+	vectorMaxDimensions: number;
+	columnTypes: DatabaseColumnTypes;
+	vectorColumnType(dimensions?: number): string;
+	vectorToDbValue(vector: readonly number[], db?: Knex): unknown;
+	vectorFromDbValue(input: unknown): number[] | null;
+	createDatabase(db: Knex, databaseName: string): Promise<void>;
+	dropDatabase(db: Knex, databaseName: string): Promise<void>;
+	quoteIdentifier(identifier: string): string;
+	getTableIndexes(db: Knex, tableName: string): Promise<TableIndexSpec[]>;
+	/**
+	 * Reads comments for the requested existing tables.
+	 *
+	 * @param db - Database connection used for metadata inspection.
+	 * @param tableNames - Model table names whose comments are required.
+	 * @returns Existing comments keyed by table name.
+	 */
+	getTableComments(
+		db: Knex,
+		tableNames: string[],
+	): Promise<Map<string, string | null>>;
+}
+
+export interface DatabaseValueOptions {
+	db?: Knex;
+	dialect?: DatabaseDialect;
+}

package/src/db/errors.ts

@@ -0,0 +1,22 @@
+import { displayNameFromIdentifier } from '@db3.ai/pure';
+
+export type ActiveRecordLookup = unknown | Record<string, unknown>;
+
+/**
+ * Error thrown when an ActiveRecord lookup cannot find a matching row.
+ */
+export class RecordNotFoundError extends Error {
+	/**
+	 * Creates a not-found error for a model lookup.
+	 *
+	 * @param modelName - Name of the model that was queried.
+	 * @param lookup - Lookup value or criteria used by the query.
+	 */
+	constructor(
+		public readonly modelName: string,
+		public readonly lookup?: ActiveRecordLookup,
+	) {
+		super(`The requested ${displayNameFromIdentifier(modelName)} could not be found.`);
+		this.name = 'RecordNotFoundError';
+	}
+}

package/src/db/examples/DefinedUser.ts

@@ -0,0 +1,20 @@
+import { ActiveRecord } from '@db3.ai/app/db';
+
+/** A user whose properties and construction inputs are inferred from its fields. */
+export class DefinedUser extends ActiveRecord.define({
+	table: 'defined_users',
+	requestFillable: ['email'],
+	fields: field => ({
+		id: field.ulid({ primary: true }),
+		email: field.email({ required: true }),
+	}),
+}) {
+	/**
+	 * Returns the domain of the normalized email, or null before it is provided.
+	 *
+	 * @returns Current email domain.
+	 */
+	emailDomain(): string | null {
+		return this.email?.split('@')[1] ?? null;
+	}
+}

package/src/db/examples/FieldNote.ts

@@ -0,0 +1,27 @@
+import { ActiveRecord, type FieldBuilder } from '@db3.ai/app/db';
+import { NoteCodeField } from './NoteCodeField';
+
+/** A disposable guide model demonstrating reusable and JSON-backed field values. */
+export class FieldNote extends ActiveRecord {
+	static override table = 'field_notes';
+	static override requestFillable = ['code', 'tags', 'metadata'];
+
+	/** Declares one place for input, validation, storage and public-output policy. */
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid(),
+			owner: field.string({ column: 'owner_id', required: true, index: true }),
+			code: new NoteCodeField({ required: true, maxLength: 20 }),
+			tags: field.stringList({ maxItems: 3, truncate: false }),
+			metadata: field.json<{ client: { name: string }; draft: boolean }>(),
+			integration: field.encryptedJson<{ token: string }>({ column: 'integration_secret', selectedByDefault: false }),
+		};
+	}
+
+	declare id: string | null;
+	declare owner: string | null;
+	declare code: string | null;
+	declare tags: string[];
+	declare metadata: { client: { name: string }; draft: boolean } | null;
+	declare integration: { token: string } | null;
+}

package/src/db/examples/KnowledgeNote.ts

@@ -0,0 +1,29 @@
+import { ActiveRecord, type FieldBuilder } from '@db3.ai/app/db';
+
+/** A workspace-owned note used by the ActiveRecord guide and executable recipe. */
+export class KnowledgeNote extends ActiveRecord {
+	static override table = 'knowledge_notes';
+	static override requestFillable = ['title', 'body'];
+
+	/**
+	 * Defines storage, validation and transport behaviour for each logical field.
+	 *
+	 * @param field - Framework field factory.
+	 * @returns The note's schema; workspace ownership is assigned by trusted code.
+	 */
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid(),
+			workspace: field.string({ column: 'workspace_id', required: true, maxLength: 26, index: true }),
+			title: field.string({ required: true, maxLength: 120 }),
+			body: field.text(),
+			createdAt: field.timestamp({ column: 'created_at', auto: 'create' }),
+		};
+	}
+
+	declare id: string | null;
+	declare workspace: string | null;
+	declare title: string | null;
+	declare body: string | null;
+	declare createdAt: Date | null;
+}

package/src/db/examples/NoteCodeField.ts

@@ -0,0 +1,9 @@
+import { StringField } from '@db3.ai/app/db';
+
+/** Reusable uppercase identifier conversion with normal string validation/storage. */
+export class NoteCodeField extends StringField {
+	/** Normalizes trusted or request input without duplicating database conversion. */
+	protected override parse(input: unknown): string | null {
+		return super.parse(input)?.toUpperCase() ?? null;
+	}
+}

package/src/db/examples/createNotesTogether.ts

@@ -0,0 +1,24 @@
+import { ActiveRecord } from '@db3.ai/app/db';
+import { app } from '@db3.ai/app/server';
+import { createWorkspaceNote } from './workspaceNotes';
+import type { KnowledgeNote } from './KnowledgeNote';
+
+/**
+ * Saves a group of notes atomically using the active application's database.
+ *
+ * Records are constructed inside the transaction scope. An error rolls back
+ * all writes; existing records bound to another connection are not rebound.
+ *
+ * @param workspaceId - Workspace the host has authorized for creation.
+ * @param inputs - Note inputs; each goes through the same filling and validation.
+ * @returns Persisted notes after the transaction commits successfully.
+ */
+export async function createNotesTogether(workspaceId: string, inputs: unknown[]): Promise<KnowledgeNote[]> {
+	return app().db.knex.transaction(transaction => ActiveRecord.withDb(transaction, async () => {
+		const notes: KnowledgeNote[] = [];
+		for (const input of inputs) {
+			notes.push(await createWorkspaceNote(workspaceId, input));
+		}
+		return notes;
+	}));
+}

package/src/db/examples/outputs/workspace-notes.json

@@ -0,0 +1,9 @@
+{
+	"title": "Client brief",
+	"visibleNotes": 1,
+	"workspaceProtected": true,
+	"jsonTimestamp": true,
+	"validationCodes": ["required"],
+	"rollbackPreservedCount": true,
+	"remainingNotes": 0
+}

package/src/db/examples/runFieldNotes.ts

@@ -0,0 +1,51 @@
+import { pathToFileURL } from 'node:url';
+import { RecordValidationError } from '@db3.ai/app/db';
+import { createGeneratedTestDatabase } from '@db3.ai/app/db/test/db';
+import { Security } from '@db3.ai/app/security';
+import { App } from '@db3.ai/app/server';
+import { FieldNote } from './FieldNote';
+
+/**
+ * Verifies field conversion and encrypted storage in an isolated SQL database.
+ *
+ * Raw SQL below is deliberately limited to checking physical storage; normal
+ * application reads use logical model fields. Only outcome booleans are printed
+ * for secret values. The generated database and ephemeral key are disposable.
+ *
+ * @returns The observed conversion, output, query and validation outcomes.
+ */
+export async function runFieldNotes() {
+	const database = await createGeneratedTestDatabase('field_notes');
+	const application = new App({ db: database.db, config: { security: { key: Security.generateKey() } } });
+	try {
+		await application.db.install(FieldNote);
+		const note = new FieldNote();
+		note.setFromRequest({ code: '  brief-1  ', tags: [' SEO ', 'seo', 'Agency'], metadata: '{"client":{"name":"Ada"},"draft":true}', owner: 'wrong-owner', integration: { token: 'untrusted' } });
+		note.assign({ owner: 'ada', integration: { token: 'synthetic-server-secret' } });
+		await note.save();
+		await FieldNote.create({ owner: 'grace', code: 'other' }).save();
+		const found = await FieldNote.where({ owner: 'ada', id: note.id }).firstOrFail();
+		const selected = await FieldNote.query().withField('integration').where({ owner: 'ada', id: note.id }).firstOrFail();
+		const physical = await application.db.knex(FieldNote.table).where({ id: note.id }).first();
+		const projected = await FieldNote.where('owner', 'ada').select('code').limit(1).all();
+		const countBefore = await FieldNote.where('owner', 'ada').count();
+		let invalidRejected = false;
+		try { await FieldNote.create({ owner: 'ada', code: ' ', tags: ['one', 'two', 'three', 'four'] }).save(); } catch (error) { if (!(error instanceof RecordValidationError)) throw error; invalidRejected = true; }
+		return {
+			code: found.code, tags: found.tags, metadata: found.metadata,
+			ownerProtected: found.owner === 'ada',
+			ciphertextStored: String(physical.integration_secret).startsWith('security:1:aes-256-gcm:') && !String(physical.integration_secret).includes('synthetic-server-secret'),
+			omittedByDefault: found.integration === null,
+			decryptedOnRequest: selected.integration?.token === 'synthetic-server-secret',
+			hiddenFromJson: !Object.hasOwn(selected.toJSON(), 'integration'),
+			projectedCode: projected[0]?.code,
+			scopedCount: countBefore,
+			invalidRejected,
+			countUnchanged: await FieldNote.where('owner', 'ada').count() === countBefore,
+		};
+	} finally {
+		try { await application.close(); } finally { await database.destroy(); }
+	}
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) console.log(JSON.stringify(await runFieldNotes(), null, 2));

package/src/db/examples/runNoteMigrations.ts

@@ -0,0 +1,64 @@
+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ActiveRecord, DatabaseMigrationManager, mariaDbDialect, type FieldBuilder } from '@db3.ai/app/db';
+import { createGeneratedTestDatabase } from '@db3.ai/app/db/test/db';
+
+/** Initial version of a disposable note table, before a schema change. */
+class InitialNote extends ActiveRecord {
+	static override table = 'migration_guide_notes';
+	/** Defines the initial committed schema. */
+	static override fields(field: FieldBuilder) { return { id: field.ulid(), title: field.string({ required: true }) }; }
+}
+
+/** Unsafe proposal: existing rows have no value for this required column. */
+class RequiredCategoryNote extends InitialNote {
+	/** Adds a required field without pretending existing data has a value. */
+	static override fields(field: FieldBuilder) { return { ...super.fields(field), category: field.string({ required: true }) }; }
+}
+
+/** Repaired additive change that can be deployed before backfilling existing rows. */
+class OptionalCategoryNote extends InitialNote {
+	/** Adds a nullable field safe for the existing note. */
+	static override fields(field: FieldBuilder) { return { ...super.fields(field), category: field.string() }; }
+}
+
+/**
+ * Generates, applies and checks migrations against an owned disposable database.
+ *
+ * The three model classes represent successive source revisions, not models an
+ * application should register together. Production apps commit reviewed files;
+ * this lab discards only its temporary migration directory and test database.
+ *
+ * @returns Generation, blocked-change, recovery and persisted-data outcomes.
+ */
+export async function runNoteMigrations() {
+	const database = await createGeneratedTestDatabase('migrations_guide');
+	const directory = await mkdtemp(join(tmpdir(), 'db3-migrations-guide-'));
+	const snapshotFile = join(directory, 'schema.snapshot.json');
+	const migrationsDirectory = join(directory, 'migrations');
+	/** Creates the manager for one simulated model-source revision. */
+	const managerFor = (Model: typeof InitialNote, second: number) => new DatabaseMigrationManager({ db: database.db, models: [Model], dialect: mariaDbDialect, migrationsDirectory, snapshotFile, environment: 'test', now: () => new Date(Date.UTC(2026, 8, 5, 12, 0, second)) });
+	try {
+		const initial = managerFor(InitialNote, 0);
+		const first = await initial.makeMigration({ name: 'initial_notes' });
+		await initial.migrate();
+		await ActiveRecord.withDb(database.db, () => InitialNote.create({ title: 'Keep this note' }).save());
+		const snapshotBefore = await readFile(snapshotFile, 'utf8');
+		const filesBefore = await readdir(migrationsDirectory);
+		const unsafe = await managerFor(RequiredCategoryNote, 1).makeMigration({ name: 'required_category' });
+		const blockedPreservedSource = snapshotBefore === await readFile(snapshotFile, 'utf8') && filesBefore.length === (await readdir(migrationsDirectory)).length;
+		const repaired = managerFor(OptionalCategoryNote, 2);
+		const second = await repaired.makeMigration({ name: 'optional_category' });
+		const pendingBefore = (await repaired.status()).migrations.pending.length;
+		const applied = await repaired.migrate();
+		const checked = await repaired.check();
+		const row = await ActiveRecord.withDb(database.db, () => OptionalCategoryNote.query().firstOrFail());
+		return { initialGenerated: first.generated, unsafeBlocked: unsafe.blocked, blockedPreservedSource, repairedGenerated: second.generated, pendingBefore, applied: applied.applied.length, matches: checked.matches, titlePreserved: row.get('title') === 'Keep this note', categoryNullable: row.get('category') === null };
+	} finally {
+		try { await database.destroy(); } finally { await rm(directory, { recursive: true, force: true }); }
+	}
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) console.log(JSON.stringify(await runNoteMigrations(), null, 2));

package/src/db/examples/runWorkspaceNotes.ts

@@ -0,0 +1,86 @@
+import { pathToFileURL } from 'node:url';
+import { RecordValidationError } from '@db3.ai/app/db';
+import { createGeneratedTestDatabase } from '@db3.ai/app/db/test/db';
+import { App } from '@db3.ai/app/server';
+import { createNotesTogether } from './createNotesTogether';
+import { KnowledgeNote } from './KnowledgeNote';
+import { createWorkspaceNote, deleteWorkspaceNote, listWorkspaceNotes, updateWorkspaceNote } from './workspaceNotes';
+
+/** Observable, deterministic outcomes from the disposable notes walkthrough. */
+export interface WorkspaceNotesOutcome {
+	/** Trimmed title read back through the model query. */
+	title: string | null;
+	/** Number of notes visible in the authorized workspace. */
+	visibleNotes: number;
+	/** Whether request filling refused a payload-supplied ownership change. */
+	workspaceProtected: boolean;
+	/** Whether transport conversion rendered the timestamp as a string. */
+	jsonTimestamp: boolean;
+	/** Validation codes returned for a blank required title. */
+	validationCodes: string[];
+	/** Whether a failed transaction left no new rows behind. */
+	rollbackPreservedCount: boolean;
+	/** Rows remaining after deleting the original workspace note. */
+	remainingNotes: number;
+}
+
+/**
+ * Runs the guide against a newly created database and removes it afterwards.
+ *
+ * Requires a local SQL account allowed to create/drop db3_app_test_* databases.
+ * Database.install is deliberately used only inside this disposable lab.
+ * Normal applications use reviewed migrations instead of boot-time schema work.
+ *
+ * @returns Actual database, validation and transport outcomes for the guide.
+ */
+export async function runWorkspaceNotes(): Promise<WorkspaceNotesOutcome> {
+	const database = await createGeneratedTestDatabase('notes_guide');
+	const application = new App({ db: database.db });
+
+	try {
+		await application.db.install(KnowledgeNote);
+		const workspace = '01ARZ3NDEKTSV4RRFFQ69G5FAV';
+		const otherWorkspace = '01ARZ3NDEKTSV4RRFFQ69G5FAW';
+		const note = await createWorkspaceNote(workspace, { title: '  Client brief  ', body: 'Prepare the proposal.', workspace: otherWorkspace });
+		await createWorkspaceNote(otherWorkspace, { title: 'Another client' });
+		const notes = await listWorkspaceNotes(workspace);
+		const updated = await updateWorkspaceNote(workspace, note.id!, { body: 'Review the brief, then prepare the proposal.' });
+		const validationCodes: string[] = [];
+
+		try {
+			await createWorkspaceNote(workspace, { title: '   ' });
+		} catch (error) {
+			if (!(error instanceof RecordValidationError)) throw error;
+			validationCodes.push(...error.errors.flatMap(field => field.code ? [field.code] : []));
+		}
+
+		const before = await KnowledgeNote.where('workspace', workspace).count();
+		try {
+			await createNotesTogether(workspace, [{ title: 'This note must roll back' }, { title: '' }]);
+		} catch (error) {
+			if (!(error instanceof RecordValidationError)) throw error;
+		}
+		const after = await KnowledgeNote.where('workspace', workspace).count();
+		await deleteWorkspaceNote(workspace, note.id!);
+
+		return {
+			title: notes[0]?.title ?? null,
+			visibleNotes: notes.length,
+			workspaceProtected: updated.workspace === workspace,
+			jsonTimestamp: typeof updated.toJSON().createdAt === 'string',
+			validationCodes,
+			rollbackPreservedCount: before === after,
+			remainingNotes: await KnowledgeNote.where('workspace', workspace).count(),
+		};
+	} finally {
+		try {
+			await application.close();
+		} finally {
+			await database.destroy();
+		}
+	}
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	console.log(JSON.stringify(await runWorkspaceNotes(), null, 2));
+}