@yunsoft/yuncms-core 0.1.1 → 0.1.3

package/README.md

@@ -3,3 +3,9 @@
 Core services, schema, authentication, permissions, hooks and storage primitives used by YunCMS.
 
 This package is installed by `@yunsoft/yuncms` and `@yunsoft/yuncms-api`. See the [project repository](https://github.com/Yunsoft-Software/yuncms) for architecture and service documentation.
+
+## Project status
+
+YunCMS is developed and maintained by [Yunsoft Software](https://yunsoft.com). It is under active development, so interfaces and behavior may change between releases. Test upgrades and keep verified backups before production use.
+
+Use YunCMS at your own risk. This package is provided under the [MIT License](https://github.com/Yunsoft-Software/yuncms/blob/16-08-2026/LICENSE) without warranty.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunsoft/yuncms-core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Core services, schema, authentication, permissions and storage primitives for YunCMS.",
   "license": "MIT",
   "type": "module",

package/src/auth/users-repository.js

@@ -1,7 +1,7 @@
 export async function readAuthenticationUserByEmail(database, email) {
   const [rows] = await database.query(
     `SELECT u.id, u.email, u.password_hash, u.role, u.status, u.email_verified_at,
-            r.admin AS role_admin, r.public AS role_public
+            r.name AS role_name, r.admin AS role_admin, r.public AS role_public
      FROM yuncms_users u
      LEFT JOIN yuncms_roles r ON r.id = u.role
      WHERE u.email = ?
@@ -14,7 +14,7 @@ export async function readAuthenticationUserByEmail(database, email) {
 export async function readAuthenticationUserById(database, id) {
   const [rows] = await database.query(
     `SELECT u.id, u.email, u.password_hash, u.role, u.status, u.email_verified_at,
-            r.admin AS role_admin, r.public AS role_public
+            r.name AS role_name, r.admin AS role_admin, r.public AS role_public
      FROM yuncms_users u
      LEFT JOIN yuncms_roles r ON r.id = u.role
      WHERE u.id = ?

package/src/bootstrap.js

@@ -6,6 +6,10 @@ import { publicRoleConstraintsMigration } from './migrations/0003-public-role-co
 import { authActionTokensMigration } from './migrations/0004-auth-action-tokens.js';
 import { defaultPublicRoleMigration } from './migrations/0005-default-public-role.js';
 import { studioSettingsMigration } from './migrations/0006-studio-settings.js';
+import { systemPermissionResourcesMigration } from './migrations/0007-system-permission-resources.js';
+import { studioLogoFileMigration } from './migrations/0008-studio-logo-file.js';
+import { schemaDisplayNamesMigration } from './migrations/0009-schema-display-names.js';
+import { studioFaviconFileMigration } from './migrations/0010-studio-favicon-file.js';
 import { readSchemaVersion } from './schema-version.js';
 import { ensurePublicRole } from './setup.js';
 
@@ -16,6 +20,10 @@ export const CORE_MIGRATIONS = Object.freeze([
   authActionTokensMigration,
   defaultPublicRoleMigration,
   studioSettingsMigration,
+  systemPermissionResourcesMigration,
+  studioLogoFileMigration,
+  schemaDisplayNamesMigration,
+  studioFaviconFileMigration,
 ]);
 
 export const REQUIRED_CORE_MIGRATION_IDS = Object.freeze(

package/src/config.js

@@ -1,5 +1,7 @@
 import { loadEnvFile } from 'node:process';
 
+export const DEFAULT_SERVER_PORT = 3008;
+
 function readInteger(value, fallback, name, { min = 0, max = Number.MAX_SAFE_INTEGER } = {}) {
   if (value === undefined || value === '') return fallback;
 
@@ -33,7 +35,7 @@ export function loadEnvFileIfPresent(path = '.env') {
 }
 
 export function loadConfig(env = process.env) {
-  const serverPort = readInteger(env.PORT, 3008, 'PORT', { min: 1, max: 65535 });
+  const serverPort = readInteger(env.PORT, DEFAULT_SERVER_PORT, 'PORT', { min: 1, max: 65535 });
   const studioOrigin = readString(env.STUDIO_ORIGIN, `http://localhost:${serverPort}`);
 
   return {

package/src/field-types.js

@@ -12,6 +12,9 @@ const TYPE_NAMES = new Set([
   'uuid',
 ]);
 
+const FILE_INTERFACES = new Set(['file', 'image']);
+const CURRENT_TIME_TYPES = new Set(['datetime', 'timestamp']);
+
 function integerOption(value, fallback, { min, max, label }) {
   const resolved = value ?? fallback;
   if (!Number.isInteger(resolved) || resolved < min || resolved > max) {
@@ -29,8 +32,47 @@ export function assertFieldType(type) {
   return type;
 }
 
+function assertInterfaceStorage(type, fieldInterface) {
+  if (!FILE_INTERFACES.has(fieldInterface)) return;
+  if (type !== 'uuid') {
+    const error = new Error(`${fieldInterface} interface requires uuid storage`);
+    error.code = 'INVALID_FIELD_INTERFACE';
+    throw error;
+  }
+}
+
+function assertTimePresets(type, input) {
+  if (Object.hasOwn(input, 'defaultValue') && input.defaultPreset != null) {
+    const error = new Error('defaultValue and defaultPreset cannot be used together');
+    error.code = 'INVALID_FIELD_DEFAULT';
+    throw error;
+  }
+  if (input.defaultPreset != null && input.defaultPreset !== 'now') {
+    const error = new Error(`Unsupported default preset: ${String(input.defaultPreset)}`);
+    error.code = 'UNSUPPORTED_FIELD_DEFAULT';
+    throw error;
+  }
+  if (input.defaultPreset === 'now' && !CURRENT_TIME_TYPES.has(type)) {
+    const error = new Error('Current-time defaults require datetime or timestamp storage');
+    error.code = 'UNSUPPORTED_FIELD_DEFAULT';
+    throw error;
+  }
+  if (input.autoUpdate != null && typeof input.autoUpdate !== 'boolean') {
+    const error = new Error('autoUpdate must be boolean');
+    error.code = 'INVALID_SCHEMA_PAYLOAD';
+    throw error;
+  }
+  if (input.autoUpdate === true && !CURRENT_TIME_TYPES.has(type)) {
+    const error = new Error('Automatic update timestamps require datetime or timestamp storage');
+    error.code = 'UNSUPPORTED_FIELD_DEFAULT';
+    throw error;
+  }
+}
+
 export function compileFieldColumn(input = {}) {
   const type = assertFieldType(input.type);
+  assertInterfaceStorage(type, input.interface);
+  assertTimePresets(type, input);
   const params = [];
   let sqlType;
 
@@ -81,7 +123,9 @@ export function compileFieldColumn(input = {}) {
   let sql = sqlType;
   sql += input.required === true ? ' NOT NULL' : ' NULL';
 
-  if (Object.hasOwn(input, 'defaultValue')) {
+  if (input.defaultPreset === 'now') {
+    sql += ' DEFAULT CURRENT_TIMESTAMP(3)';
+  } else if (Object.hasOwn(input, 'defaultValue')) {
     if (type === 'text' || type === 'json') {
       const error = new Error(`Defaults for ${type} fields are postponed in V1`);
       error.code = 'UNSUPPORTED_FIELD_DEFAULT';
@@ -97,6 +141,8 @@ export function compileFieldColumn(input = {}) {
     }
   }
 
+  if (input.autoUpdate === true) sql += ' ON UPDATE CURRENT_TIMESTAMP(3)';
+
   return {
     sql,
     params,
@@ -105,6 +151,8 @@ export function compileFieldColumn(input = {}) {
       precision: type === 'decimal' ? (input.precision ?? 18) : undefined,
       scale: type === 'decimal' ? (input.scale ?? 2) : undefined,
       defaultValue: Object.hasOwn(input, 'defaultValue') ? input.defaultValue : undefined,
+      defaultPreset: input.defaultPreset ?? undefined,
+      autoUpdate: input.autoUpdate === true ? true : undefined,
     },
   };
 }

package/src/index.js

@@ -1,7 +1,8 @@
-export { loadConfig, loadEnvFileIfPresent } from './config.js';
+export { DEFAULT_SERVER_PORT, loadConfig, loadEnvFileIfPresent } from './config.js';
 export { createDatabasePool, pingDatabase, closeDatabasePool } from './database.js';
 export { withTransaction, withConnectionTransaction } from './transaction.js';
 export { assertIdentifier, quoteIdentifier } from './identifier.js';
+export { normalizeDisplayName, normalizeSchemaKey, resolveSchemaName } from './schema-key.js';
 export { YunCmsDatabaseError, normalizeDatabaseError, isRetryableDatabaseError } from './errors.js';
 export { withDatabaseRetry } from './retry.js';
 export {
@@ -20,6 +21,7 @@ export {
 export { HookEmitter } from './hooks.js';
 export { createJsonLogger, LEVELS as LOG_LEVELS } from './logger.js';
 export { deleteM2MJunction } from './m2m-lifecycle.js';
+export { createO2ORelation, deleteO2ORelation, o2oUniqueIndexName } from './o2o-relation.js';
 export {
   MAX_EXPAND_FIELDS,
   parseExpandInput,
@@ -40,6 +42,7 @@ export { AuditService, redactAuditValue } from './services/audit-service.js';
 export { ItemsService } from './services/items-service.js';
 export { CollectionsService } from './services/collections-service.js';
 export { FieldsService } from './services/fields-service.js';
+export { SystemCollectionFieldsService } from './services/system-collection-fields-service.js';
 export { RelationsService } from './services/relations-service.js';
 export { UsersService } from './services/users-service.js';
 export { RolesService } from './services/roles-service.js';
@@ -50,6 +53,20 @@ export { StudioSettingsService, STUDIO_SETTING_DEFAULTS } from './services/studi
 export { SchemaMetadataRepository } from './schema-metadata-repository.js';
 export { loadSchemaSnapshot, SchemaCache } from './schema.js';
 export { assertFieldType, compileFieldColumn } from './field-types.js';
+export {
+  COLLECTION_SYSTEM_FIELDS,
+  compileCollectionSystemFields,
+  fieldSpecial,
+  isSystemManagedField,
+  normalizeCollectionSystemFields,
+  systemMutationEntries,
+} from './system-fields.js';
+export {
+  assertActionOnlyPermissionPayload,
+  assertSystemResourceAction,
+  isPermissionManagedSystemResource,
+  systemPermissionConfig,
+} from './system-permissions.js';
 export {
   parseItemsQuery,
   compileSelectFields,

package/src/migrations/0007-system-permission-resources.js

@@ -0,0 +1,46 @@
+export const systemPermissionResourcesMigration = {
+  id: '0007-system-permission-resources',
+  statements: [
+    `INSERT IGNORE INTO yuncms_collections
+      (collection, primary_key, note, singleton, hidden, \`system\`, metadata)
+     VALUES
+      ('yuncms_users', 'id', 'System users resource', 0, 1, 1,
+        JSON_OBJECT('permissionManaged', TRUE, 'permissionMode', 'action-only', 'resource', 'users',
+          'allowedActions', JSON_ARRAY('read', 'create', 'update', 'delete'))),
+      ('yuncms_files', 'id', 'System files resource', 0, 1, 1,
+        JSON_OBJECT('permissionManaged', TRUE, 'permissionMode', 'action-only', 'resource', 'files',
+          'allowedActions', JSON_ARRAY('read', 'create', 'update', 'delete'))),
+      ('yuncms_roles', 'id', 'System roles resource', 0, 1, 1,
+        JSON_OBJECT('permissionManaged', TRUE, 'permissionMode', 'action-only', 'resource', 'roles',
+          'allowedActions', JSON_ARRAY('read')))`,
+
+    `INSERT IGNORE INTO yuncms_fields
+      (collection, field, type, required, readonly, hidden, interface, schema_metadata)
+     VALUES
+      ('yuncms_users', 'id', 'uuid', 1, 1, 0, 'input', JSON_OBJECT('primaryKey', TRUE, 'length', 36)),
+      ('yuncms_users', 'email', 'string', 1, 0, 0, 'input', JSON_OBJECT('length', 191)),
+      ('yuncms_users', 'role', 'uuid', 0, 0, 0, 'input', JSON_OBJECT('length', 36)),
+      ('yuncms_users', 'status', 'string', 1, 0, 0, 'input', JSON_OBJECT('length', 32)),
+      ('yuncms_users', 'email_verified_at', 'datetime', 0, 1, 0, 'datetime', NULL),
+      ('yuncms_users', 'last_access', 'datetime', 0, 1, 0, 'datetime', NULL),
+      ('yuncms_users', 'created_at', 'datetime', 1, 1, 0, 'datetime', JSON_OBJECT('special', 'date-created', 'systemManaged', TRUE)),
+      ('yuncms_users', 'updated_at', 'datetime', 1, 1, 0, 'datetime', JSON_OBJECT('special', 'date-updated', 'systemManaged', TRUE)),
+
+      ('yuncms_files', 'id', 'uuid', 1, 1, 0, 'input', JSON_OBJECT('primaryKey', TRUE, 'length', 36)),
+      ('yuncms_files', 'storage', 'string', 1, 1, 0, 'input', JSON_OBJECT('length', 64)),
+      ('yuncms_files', 'filename_download', 'string', 1, 0, 0, 'input', JSON_OBJECT('length', 255)),
+      ('yuncms_files', 'title', 'string', 0, 0, 0, 'input', JSON_OBJECT('length', 255)),
+      ('yuncms_files', 'mimetype', 'string', 0, 1, 0, 'input', JSON_OBJECT('length', 191)),
+      ('yuncms_files', 'filesize', 'bigint', 0, 1, 0, 'input', NULL),
+      ('yuncms_files', 'uploaded_by', 'uuid', 0, 1, 0, 'user', JSON_OBJECT('length', 36)),
+      ('yuncms_files', 'uploaded_at', 'datetime', 1, 1, 0, 'datetime', JSON_OBJECT('special', 'date-created', 'systemManaged', TRUE)),
+
+      ('yuncms_roles', 'id', 'uuid', 1, 1, 0, 'input', JSON_OBJECT('primaryKey', TRUE, 'length', 36)),
+      ('yuncms_roles', 'name', 'string', 1, 1, 0, 'input', JSON_OBJECT('length', 100)),
+      ('yuncms_roles', 'description', 'text', 0, 1, 0, 'textarea', NULL),
+      ('yuncms_roles', 'admin', 'boolean', 1, 1, 0, 'boolean', NULL),
+      ('yuncms_roles', 'public', 'boolean', 1, 1, 0, 'boolean', NULL)`,
+
+    `UPDATE yuncms_schema_state SET version = version + 1 WHERE id = 1`,
+  ],
+};

package/src/migrations/0008-studio-logo-file.js

@@ -0,0 +1,10 @@
+export const studioLogoFileMigration = {
+  id: '0008-studio-logo-file',
+  statements: [
+    `ALTER TABLE yuncms_studio_settings
+       ADD COLUMN logo_file CHAR(36) NULL AFTER logo_url,
+       ADD KEY idx_yuncms_studio_settings_logo_file (logo_file),
+       ADD CONSTRAINT fk_yuncms_studio_settings_logo_file
+         FOREIGN KEY (logo_file) REFERENCES yuncms_files (id) ON DELETE SET NULL`,
+  ],
+};

package/src/migrations/0009-schema-display-names.js

@@ -0,0 +1,19 @@
+export const schemaDisplayNamesMigration = {
+  id: '0009-schema-display-names',
+  statements: [
+    `ALTER TABLE yuncms_collections
+      ADD COLUMN name VARCHAR(255) NULL AFTER collection`,
+    `UPDATE yuncms_collections
+      SET name = collection
+      WHERE name IS NULL OR TRIM(name) = ''`,
+    `ALTER TABLE yuncms_collections
+      MODIFY COLUMN name VARCHAR(255) NOT NULL`,
+    `ALTER TABLE yuncms_fields
+      ADD COLUMN name VARCHAR(255) NULL AFTER field`,
+    `UPDATE yuncms_fields
+      SET name = field
+      WHERE name IS NULL OR TRIM(name) = ''`,
+    `ALTER TABLE yuncms_fields
+      MODIFY COLUMN name VARCHAR(255) NOT NULL`,
+  ],
+};

package/src/migrations/0010-studio-favicon-file.js

@@ -0,0 +1,12 @@
+export const studioFaviconFileMigration = {
+  id: '0010-studio-favicon-file',
+  statements: [
+    `ALTER TABLE yuncms_studio_settings
+      ADD COLUMN favicon_file CHAR(36) NULL AFTER logo_file`,
+    `ALTER TABLE yuncms_studio_settings
+      ADD KEY idx_yuncms_studio_settings_favicon_file (favicon_file)`,
+    `ALTER TABLE yuncms_studio_settings
+      ADD CONSTRAINT fk_yuncms_studio_settings_favicon_file
+      FOREIGN KEY (favicon_file) REFERENCES yuncms_files (id) ON DELETE SET NULL`,
+  ],
+};

package/src/o2o-relation.js

@@ -0,0 +1,231 @@
+import { createHash } from 'node:crypto';
+
+import { withAdvisoryLock } from './advisory-lock.js';
+import { assertIdentifier, quoteIdentifier } from './identifier.js';
+import { SchemaMetadataRepository } from './schema-metadata-repository.js';
+import { incrementSchemaVersion } from './schema-version.js';
+import { withConnectionTransaction } from './transaction.js';
+import { assertSchemaManager } from './services/schema-access.js';
+
+const ON_DELETE_ACTIONS = new Set(['RESTRICT', 'CASCADE', 'SET NULL']);
+
+function parseMetadata(value) {
+  if (!value) return {};
+  if (typeof value === 'object') return value;
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function assertOnDelete(value) {
+  const action = String(value ?? 'RESTRICT').toUpperCase();
+  if (!ON_DELETE_ACTIONS.has(action)) {
+    const error = new Error(`Unsupported ON DELETE action: ${action}`);
+    error.code = 'INVALID_ON_DELETE';
+    throw error;
+  }
+  return action;
+}
+
+function constraintName(manyCollection, manyField, oneCollection) {
+  const digest = createHash('sha256')
+    .update(`${manyCollection}:${manyField}:${oneCollection}`)
+    .digest('hex')
+    .slice(0, 24);
+  return `yfk_${digest}`;
+}
+
+export function o2oUniqueIndexName(collection, field) {
+  const digest = createHash('sha256')
+    .update(`${collection}:${field}:o2o`)
+    .digest('hex')
+    .slice(0, 24);
+  return `yuo_${digest}`;
+}
+
+export async function createO2ORelation({ database, accountability, input = {} }) {
+  assertSchemaManager(accountability);
+  const manyCollection = assertIdentifier(input.manyCollection, 'one-to-one source collection');
+  const manyField = assertIdentifier(input.manyField, 'one-to-one source field');
+  const oneCollection = assertIdentifier(input.oneCollection, 'one-to-one target collection');
+  const onDelete = assertOnDelete(input.onDelete);
+
+  return withAdvisoryLock(database, 'yuncms:schema', async (connection) => {
+    const metadata = new SchemaMetadataRepository(connection);
+    const [manyCollectionMetadata, oneCollectionMetadata] = await Promise.all([
+      metadata.readCollection(manyCollection),
+      metadata.readCollection(oneCollection),
+    ]);
+
+    if (!manyCollectionMetadata || !oneCollectionMetadata) {
+      const error = new Error('Both one-to-one collections must exist');
+      error.code = 'COLLECTION_NOT_FOUND';
+      throw error;
+    }
+    if (manyCollectionMetadata.system || oneCollectionMetadata.system) {
+      const error = new Error('System collections cannot be changed through the dynamic relation API');
+      error.code = 'SYSTEM_SCHEMA_READ_ONLY';
+      throw error;
+    }
+
+    const oneField = input.oneField ?? oneCollectionMetadata.primary_key;
+    assertIdentifier(oneField, 'one-to-one target field');
+    if (oneField !== oneCollectionMetadata.primary_key) {
+      const error = new Error('One-to-one relations must reference the target collection primary key');
+      error.code = 'UNSUPPORTED_RELATION_TARGET';
+      throw error;
+    }
+
+    const [manyFieldMetadata, oneFieldMetadata, existingRelation] = await Promise.all([
+      metadata.readField(manyCollection, manyField),
+      metadata.readField(oneCollection, oneField),
+      metadata.readRelation(manyCollection, manyField),
+    ]);
+    if (!manyFieldMetadata || !oneFieldMetadata) {
+      const error = new Error('Both one-to-one fields must exist in schema metadata');
+      error.code = 'FIELD_NOT_FOUND';
+      throw error;
+    }
+    if (existingRelation) {
+      const error = new Error(`Relation already exists for ${manyCollection}.${manyField}`);
+      error.code = 'RELATION_EXISTS';
+      throw error;
+    }
+    if (manyFieldMetadata.type !== oneFieldMetadata.type) {
+      const error = new Error(`Relation field types do not match: ${manyFieldMetadata.type} -> ${oneFieldMetadata.type}`);
+      error.code = 'RELATION_TYPE_MISMATCH';
+      throw error;
+    }
+    if (onDelete === 'SET NULL' && Boolean(manyFieldMetadata.required)) {
+      const error = new Error('SET NULL cannot be used with a required one-to-one field');
+      error.code = 'INVALID_ON_DELETE';
+      throw error;
+    }
+
+    const fkName = constraintName(manyCollection, manyField, oneCollection);
+    const uniqueIndex = o2oUniqueIndexName(manyCollection, manyField);
+    const tableSql = quoteIdentifier(manyCollection, 'one-to-one source collection');
+    const fieldSql = quoteIdentifier(manyField, 'one-to-one source field');
+    const targetTableSql = quoteIdentifier(oneCollection, 'one-to-one target collection');
+    const targetFieldSql = quoteIdentifier(oneField, 'one-to-one target field');
+    const constraintSql = quoteIdentifier(fkName, 'one-to-one foreign key');
+    const uniqueSql = quoteIdentifier(uniqueIndex, 'one-to-one unique index');
+    let physicalRelationCreated = false;
+
+    try {
+      await connection.query(
+        `ALTER TABLE ${tableSql}
+         ADD CONSTRAINT ${constraintSql}
+           FOREIGN KEY (${fieldSql}) REFERENCES ${targetTableSql} (${targetFieldSql})
+           ON DELETE ${onDelete},
+         ADD UNIQUE INDEX ${uniqueSql} (${fieldSql})`,
+      );
+      physicalRelationCreated = true;
+
+      return await withConnectionTransaction(connection, async () => {
+        const created = await metadata.createRelation({
+          manyCollection,
+          manyField,
+          oneCollection,
+          oneField,
+          onDelete,
+          metadata: { constraintName: fkName, kind: 'o2o', uniqueIndex },
+        });
+        const schemaVersion = await incrementSchemaVersion(connection);
+        return { ...created, schemaVersion };
+      });
+    } catch (error) {
+      const cleanupErrors = [];
+      try {
+        await metadata.deleteRelation(manyCollection, manyField);
+      } catch (cleanupError) {
+        cleanupErrors.push(cleanupError);
+      }
+      if (physicalRelationCreated) {
+        try {
+          await connection.query(
+            `ALTER TABLE ${tableSql}
+             DROP FOREIGN KEY ${constraintSql},
+             DROP INDEX ${uniqueSql}`,
+          );
+        } catch (cleanupError) {
+          cleanupErrors.push(cleanupError);
+        }
+      }
+      if (cleanupErrors.length > 0) {
+        error.cleanupErrors = cleanupErrors;
+        error.code ||= 'SCHEMA_PARTIAL_FAILURE';
+      }
+      throw error;
+    }
+  });
+}
+
+export async function deleteO2ORelation({ database, accountability, manyCollection, manyField }) {
+  assertSchemaManager(accountability);
+  assertIdentifier(manyCollection, 'one-to-one source collection');
+  assertIdentifier(manyField, 'one-to-one source field');
+
+  return withAdvisoryLock(database, 'yuncms:schema', async (connection) => {
+    const metadata = new SchemaMetadataRepository(connection);
+    const relation = await metadata.readRelation(manyCollection, manyField);
+    if (!relation) {
+      const error = new Error(`Unknown relation: ${manyCollection}.${manyField}`);
+      error.code = 'RELATION_NOT_FOUND';
+      throw error;
+    }
+
+    const relationMetadata = parseMetadata(relation.metadata);
+    if (relationMetadata.kind !== 'o2o') {
+      const error = new Error(`Relation is not one-to-one: ${manyCollection}.${manyField}`);
+      error.code = 'RELATION_TYPE_MISMATCH';
+      throw error;
+    }
+
+    const tableSql = quoteIdentifier(relation.many_collection, 'one-to-one source collection');
+    const fieldSql = quoteIdentifier(relation.many_field, 'one-to-one source field');
+    const targetTableSql = quoteIdentifier(relation.one_collection, 'one-to-one target collection');
+    const targetFieldSql = quoteIdentifier(relation.one_field, 'one-to-one target field');
+    const constraintSql = quoteIdentifier(relationMetadata.constraintName, 'one-to-one foreign key');
+    const uniqueSql = quoteIdentifier(
+      relationMetadata.uniqueIndex || o2oUniqueIndexName(manyCollection, manyField),
+      'one-to-one unique index',
+    );
+
+    await connection.query(
+      `ALTER TABLE ${tableSql}
+       DROP FOREIGN KEY ${constraintSql},
+       DROP INDEX ${uniqueSql}`,
+    );
+
+    try {
+      return await withConnectionTransaction(connection, async () => {
+        const deleted = await metadata.deleteRelation(manyCollection, manyField);
+        if (deleted !== 1) {
+          const error = new Error(`Relation metadata disappeared during delete: ${manyCollection}.${manyField}`);
+          error.code = 'SCHEMA_METADATA_DRIFT';
+          throw error;
+        }
+        const schemaVersion = await incrementSchemaVersion(connection);
+        return { deleted: true, schemaVersion };
+      });
+    } catch (error) {
+      try {
+        await connection.query(
+          `ALTER TABLE ${tableSql}
+           ADD CONSTRAINT ${constraintSql}
+             FOREIGN KEY (${fieldSql}) REFERENCES ${targetTableSql} (${targetFieldSql})
+             ON DELETE ${relation.on_delete},
+           ADD UNIQUE INDEX ${uniqueSql} (${fieldSql})`,
+        );
+      } catch (restoreError) {
+        error.restoreError = restoreError;
+        error.code ||= 'SCHEMA_PARTIAL_FAILURE';
+      }
+      throw error;
+    }
+  });
+}

package/src/schema-key.js

@@ -0,0 +1,54 @@
+const TURKISH_ASCII = Object.freeze({
+  ç: 'c',
+  Ç: 'c',
+  ğ: 'g',
+  Ğ: 'g',
+  ı: 'i',
+  İ: 'i',
+  ö: 'o',
+  Ö: 'o',
+  ş: 's',
+  Ş: 's',
+  ü: 'u',
+  Ü: 'u',
+});
+
+function schemaNameError(message) {
+  const error = new Error(message);
+  error.code = 'INVALID_SCHEMA_NAME';
+  return error;
+}
+
+export function normalizeDisplayName(value, { fallback = null, maxLength = 255 } = {}) {
+  const candidate = typeof value === 'string' ? value.trim().replace(/\s+/g, ' ') : '';
+  const normalized = candidate || (typeof fallback === 'string' ? fallback.trim().replace(/\s+/g, ' ') : '');
+  if (!normalized) throw schemaNameError('A display name is required');
+  if (normalized.length > maxLength) throw schemaNameError(`Display name cannot exceed ${maxLength} characters`);
+  return normalized;
+}
+
+export function normalizeSchemaKey(value, { prefix = 'field', maxLength = 64 } = {}) {
+  const source = normalizeDisplayName(value, { maxLength: 512 });
+  const transliterated = [...source].map((character) => TURKISH_ASCII[character] ?? character).join('');
+  let key = transliterated
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .replace(/_+/g, '_');
+
+  if (!key) throw schemaNameError('Name must contain at least one letter or number');
+  if (/^[0-9]/.test(key)) key = `${prefix}_${key}`;
+  if (key.length > maxLength) key = key.slice(0, maxLength).replace(/_+$/g, '');
+  if (!key) throw schemaNameError('Name cannot be normalized to a schema key');
+  return key;
+}
+
+export function resolveSchemaName({ displayName, key, prefix = 'field' } = {}) {
+  const name = normalizeDisplayName(displayName ?? key);
+  return {
+    name,
+    key: normalizeSchemaKey(key ?? name, { prefix }),
+  };
+}