@restforgejs/platform 5.1.6 → 5.1.16

package/generators/lib/dbschema-kit/emitters/create-table.js

@@ -1,6 +1,14 @@
 'use strict';
 
 const { generateConstraintName, deriveCompositeShortName, shortenIdentifier } = require('../naming');
+const {
+  IS_DELETED_COLUMN,
+  DELETED_AT_COLUMN,
+  DELETED_BY_COLUMN,
+  isSoftDeleteEnabled,
+  assertSoftDeletePostgresOnly,
+  softDeleteCheckName
+} = require('../soft-delete-constants');
 
 const COLUMN_INDENT = '    ';
 
@@ -17,6 +25,10 @@ const OP_TO_SQL = {
 function emitCreateTable(ir, dialect) {
   const { tableName, fields, primaryKey, uniques, relations, checks } = ir;
 
+  // Guard Fase 1: soft-delete hanya didukung PostgreSQL. Non-PG + softDelete → ERROR
+  // (jangan emit bentuk boolean VARCHAR salah diam-diam).
+  assertSoftDeletePostgresOnly(ir, dialect);
+
   const lines = [];
 
   for (const [fieldName, field] of Object.entries(fields)) {
@@ -56,9 +68,45 @@ function emitCreateTable(ir, dialect) {
     lines.push(emitCheck(check, checkNames[i], dialect));
   }
 
+  // CHECK konsistensi soft-delete (R8). Artifact IMPLISIT: tidak pernah ditulis di SDF,
+  // selalu diturunkan dari `softDelete.enabled` (pola sama dengan deriveBooleanChecks).
+  // Compound multi-field, jadi TIDAK lewat jalur emitCheck generik (single-field).
+  if (isSoftDeleteEnabled(ir)) {
+    lines.push(emitSoftDeleteCheck(tableName, dialect));
+  }
+
   return `CREATE TABLE ${dialect.formatTableIdentifier(ir)} (\n${lines.join(',\n')}\n)`;
 }
 
+/**
+ * Emit CHECK konsistensi tiga kolom soft-delete (R8). Bentuk PostgreSQL (Fase 1,
+ * boolean native):
+ *
+ *   CONSTRAINT <name> CHECK (
+ *       (is_deleted = TRUE  AND deleted_at IS NOT NULL AND deleted_by IS NOT NULL)
+ *    OR (is_deleted = FALSE AND deleted_at IS NULL     AND deleted_by IS NULL)
+ *   )
+ *
+ * Nama deterministik via softDeleteCheckName (sumber tunggal di soft-delete-constants,
+ * bukan auto-name DB) agar Phase 03 (diff/introspect) mencocokkan dengan derivasi nama
+ * yang sama. Identifier kolom lewat dialect.quoteIdentifier (PostgreSQL: tanpa quote
+ * untuk identifier snake_case).
+ *
+ * @param {string} tableName - nama tabel tak-qualified (untuk nama constraint)
+ * @param {Object} dialect - dialect aktif (dijamin PostgreSQL oleh guard di pemanggil)
+ * @returns {string} satu baris constraint ber-indent siap join ke body CREATE TABLE
+ */
+function emitSoftDeleteCheck(tableName, dialect) {
+  const name = softDeleteCheckName(tableName, dialect.maxIdentifierLength);
+  const isDeleted = dialect.quoteIdentifier(IS_DELETED_COLUMN);
+  const deletedAt = dialect.quoteIdentifier(DELETED_AT_COLUMN);
+  const deletedBy = dialect.quoteIdentifier(DELETED_BY_COLUMN);
+  const expr =
+    `(${isDeleted} = TRUE AND ${deletedAt} IS NOT NULL AND ${deletedBy} IS NOT NULL)` +
+    ` OR (${isDeleted} = FALSE AND ${deletedAt} IS NULL AND ${deletedBy} IS NULL)`;
+  return `${COLUMN_INDENT}CONSTRAINT ${dialect.quoteIdentifier(name)} CHECK (${expr})`;
+}
+
 /**
  * Derive CHECK constraint penanda boolean untuk dialect yang menyimpan boolean
  * sebagai VARCHAR (mysql/oracle/sqlite). Bentuk: `col IN ('true','false')`.

package/generators/lib/dbschema-kit/introspect-mapper.js

@@ -29,7 +29,28 @@
  * @module lib/dbschema-kit/introspect-mapper
  */
 
-function mapTableMetaToIR(tableMeta, dialect) {
+const { DIALECTS } = require('./dialect');
+const {
+    SOFT_DELETE_COLUMNS,
+    SOFT_DELETE_COLUMN_TYPES,
+    SOFT_DELETE_PHASE1_DIALECT,
+    softDeleteCheckName,
+    buildSoftDeleteCheckSql
+} = require('./soft-delete-constants');
+
+/**
+ * Map raw DB metadata ke IR dbschema-kit.
+ *
+ * @param {Object} tableMeta - metadata tabel (lihat doc input shape di atas).
+ * @param {string} [dialect] - id dialect ('postgres' default).
+ * @param {Object} [options]
+ * @param {boolean} [options.strictSoftDelete=false] - bila true (jalur `introspect`),
+ *   tabel dengan kolom soft-delete tidak lengkap / tipe salah / CHECK hilang melempar
+ *   ERROR (R6). Bila false (jalur `diff`/`apply`), tabel tersebut TIDAK diakui sebagai
+ *   soft-delete (softDelete tidak di-set) sehingga `diff` melaporkannya sebagai drift
+ *   apa adanya (Detection-only), bukan crash.
+ */
+function mapTableMetaToIR(tableMeta, dialect, options) {
     if (!tableMeta || typeof tableMeta !== 'object') {
         throw new Error('mapTableMetaToIR: tableMeta is required');
     }
@@ -37,6 +58,7 @@ function mapTableMetaToIR(tableMeta, dialect) {
         throw new Error('mapTableMetaToIR: tableMeta.tableName must be a non-empty string');
     }
 
+    const opts = options || {};
     const dialectId = (dialect || 'postgres').toLowerCase();
     const tableName = tableMeta.tableName;
     const schemaName = (typeof tableMeta.schemaName === 'string' && tableMeta.schemaName !== '')
@@ -67,6 +89,19 @@ function mapTableMetaToIR(tableMeta, dialect) {
         fields[primaryKey[0]].pk = true;
     }
 
+    // ── Soft-delete detection (R6, reverse) ──────────────────
+    // Deteksi tabel soft-delete dari kolom + CHECK konsistensi (name-based). Hasil
+    // dipakai untuk: (a) mengecualikan CHECK soft-delete dari `checks` generik (R8
+    // poin 2: artifact implisit, tidak boleh muncul sebagai check manual / unparsable),
+    // dan (b) men-set `softDelete: { enabled: true }` pada IR bila valid. Strict mode
+    // (`introspect`) melempar ERROR untuk kondisi tidak valid (R6).
+    const softDeleteDetection = detectSoftDelete(tableName, fields, rawChecks, dialectId);
+    if (softDeleteDetection.state === 'invalid' && opts.strictSoftDelete === true) {
+        const err = new Error(buildSoftDeleteIntrospectError(tableName, softDeleteDetection, dialectId));
+        err.isSoftDeleteIntrospectError = true;
+        throw err;
+    }
+
     // ── Uniques: split single vs composite ───────────────────
     const compositeUniques = [];
     for (const u of rawUniques) {
@@ -141,6 +176,13 @@ function mapTableMetaToIR(tableMeta, dialect) {
     const checks = [];
     for (const c of rawChecks) {
         if (!c) continue;
+        // CHECK konsistensi soft-delete (R8) ditangani lewat blok `softDelete`, BUKAN
+        // jalur `checks` generik. Kecualikan by NAMA agar tidak muncul sebagai check
+        // manual / unparsable (false drift di diff, atau ter-emit ke SDF). Hanya
+        // dikecualikan bila tabel memang membawa kolom soft-delete (state != 'none').
+        if (softDeleteDetection.state !== 'none' && c.name && c.name === softDeleteDetection.checkName) {
+            continue;
+        }
         if (typeof c.field === 'string' && typeof c.op === 'string') {
             // Already parsed shape (test fixtures may pass this).
             checks.push(Object.assign({}, c));
@@ -157,7 +199,7 @@ function mapTableMetaToIR(tableMeta, dialect) {
         }
     }
 
-    return {
+    const ir = {
         tableName,
         schemaName,
         qualifiedName,
@@ -173,6 +215,116 @@ function mapTableMetaToIR(tableMeta, dialect) {
             autoGeneratedRelations: []
         }
     };
+
+    // R6/R8 poin 2: tabel soft-delete valid → emit blok `softDelete` minimal (hanya
+    // `enabled`). `reusable`/base-length adalah intent developer yang tidak tersimpan
+    // di DB, jadi tidak diturunkan introspect. Hanya di-attach saat valid agar tabel
+    // non-soft-delete tetap byte-identik (tidak ada key baru di IR).
+    if (softDeleteDetection.state === 'valid') {
+        ir.softDelete = { enabled: true };
+    }
+
+    return ir;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Soft-delete detection (R6, reverse)
+// ─────────────────────────────────────────────────────────────
+
+function resolveMaxIdentifierLength(dialectId) {
+    const d = DIALECTS[dialectId];
+    return d && typeof d.maxIdentifierLength === 'number' ? d.maxIdentifierLength : 63;
+}
+
+/**
+ * Deteksi status soft-delete sebuah tabel dari `fields` (sudah ber-tipe logical) dan
+ * `rawChecks` ({ name, expression }). Strategi pengenalan CHECK adalah NAME-BASED:
+ * cocokkan nama CHECK terhadap `softDeleteCheckName(table, maxLen)` (derivasi identik
+ * dengan emitter forward Phase 02). Name-based dipilih karena (a) nama deterministik
+ * dijamin emitter, dan (b) klausa CHECK compound tidak parsable oleh parser single-field
+ * sehingga content-based akan rapuh. `maxLen` diambil dari dialect agar tabel bernama
+ * panjang yang ter-truncate tetap cocok (tidak false drift).
+ *
+ * Hanya PostgreSQL (Fase 1 PostgreSQL-only). Dialect lain → 'none' (tidak diakui).
+ *
+ * @returns {{state:'none'}|{state:'valid',checkName:string}|{state:'invalid',present,missing,typeMismatches,hasCheck,checkName}}
+ */
+function detectSoftDelete(tableName, fields, rawChecks, dialectId) {
+    if (dialectId !== SOFT_DELETE_PHASE1_DIALECT) {
+        return { state: 'none' };
+    }
+
+    const present = SOFT_DELETE_COLUMNS.filter((c) => !!fields[c]);
+    if (present.length === 0) {
+        return { state: 'none' };
+    }
+
+    const maxLen = resolveMaxIdentifierLength(dialectId);
+    const checkName = softDeleteCheckName(tableName, maxLen);
+
+    const missing = SOFT_DELETE_COLUMNS.filter((c) => !fields[c]);
+    const typeMismatches = [];
+    for (const c of SOFT_DELETE_COLUMNS) {
+        const f = fields[c];
+        if (f && f.type !== SOFT_DELETE_COLUMN_TYPES[c]) {
+            typeMismatches.push({ column: c, expected: SOFT_DELETE_COLUMN_TYPES[c], actual: f.type });
+        }
+    }
+    const hasCheck = Array.isArray(rawChecks)
+        && rawChecks.some((c) => c && c.name === checkName);
+
+    if (missing.length === 0 && typeMismatches.length === 0 && hasCheck) {
+        return { state: 'valid', checkName };
+    }
+    return {
+        state: 'invalid',
+        present: present.slice(),
+        missing,
+        typeMismatches,
+        hasCheck,
+        checkName
+    };
+}
+
+/**
+ * Bangun pesan ERROR introspect (R6) sesuai kondisi yang gagal. Untuk CHECK hilang
+ * (kolom lengkap + tipe benar) menyertakan rekomendasi SQL native PostgreSQL (R8).
+ */
+function buildSoftDeleteIntrospectError(tableName, detection, dialectId) {
+    const maxLen = resolveMaxIdentifierLength(dialectId);
+    const lines = [`[restforge] ERROR: introspect blocked for table '${tableName}'`, ''];
+
+    if (detection.missing.length > 0) {
+        lines.push('  The table has some soft-delete columns, but the set is incomplete.');
+        lines.push(`    Columns found   : ${detection.present.join(', ')}`);
+        lines.push(`    Columns missing : ${detection.missing.join(', ')}`);
+        lines.push('');
+        lines.push('  Soft-delete requires all three columns (is_deleted, deleted_at, deleted_by).');
+        lines.push('  Options: add the missing columns + the consistency CHECK, OR drop the soft-delete columns.');
+    } else if (detection.typeMismatches.length > 0) {
+        lines.push('  The soft-delete columns are complete, but their types do not match the contract (R5):');
+        for (const tm of detection.typeMismatches) {
+            lines.push(`    - ${tm.column}: found '${tm.actual}', required '${tm.expected}'`);
+        }
+        lines.push('');
+        lines.push('  Options: fix the column types to match the contract, OR drop the soft-delete columns.');
+    } else {
+        // Kolom lengkap + tipe benar, CHECK hilang → bentuk R8 + rekomendasi SQL.
+        lines.push('  The soft-delete columns are complete and correctly typed, but the consistency');
+        lines.push('  CHECK constraint was not found. RESTForge refuses to generate a soft-delete SDF');
+        lines.push('  without a data-level consistency guarantee.');
+        lines.push('');
+        lines.push('  Options:');
+        lines.push('    1. Drop the is_deleted, deleted_at, deleted_by columns, OR');
+        lines.push('    2. Add the following CHECK, then re-run introspect:');
+        lines.push('');
+        const sql = buildSoftDeleteCheckSql(tableName, maxLen);
+        for (const sqlLine of sql.split('\n')) {
+            lines.push(`  ${sqlLine}`);
+        }
+    }
+
+    return lines.join('\n');
 }
 
 // ─────────────────────────────────────────────────────────────

package/generators/lib/dbschema-kit/ir-builder.js

@@ -4,6 +4,12 @@ const { parseFieldShorthand } = require('./parser/shorthand-parser');
 
 const VALID_CHECK_OPS = new Set(['in', 'gt', 'gte', 'lt', 'lte', 'eq', 'neq']);
 
+// Soft-delete (Fase 1) — blok ini sengaja ketat (R1): key tak dikenal ditolak,
+// bukan di-drop diam-diam. Whitelist khusus blok `softDelete`; tidak mengubah
+// keleluasaan blok SDF lain (relations/checks/indexes tetap lenient).
+const SOFT_DELETE_ALLOWED_KEYS = new Set(['enabled', 'reusable']);
+const SOFT_DELETE_REUSABLE_ALLOWED_KEYS = new Set(['field', 'length']);
+
 // Token boundary detection: autoUpdate must stand alone, not part of `default:autoUpdate` or `autoUpdated`
 const AUTO_UPDATE_TOKEN_RE = /(?:^|\s)autoUpdate(?=\s|$)/;
 const AUTO_UPDATE_TOKEN_RE_G = /(?:^|\s)autoUpdate(?=\s|$)/g;
@@ -44,8 +50,9 @@ function buildIR(tableName, options) {
   const indexes = normalizeIndexes(options.indexes, indexFromFk);
   const uniques = normalizeUniques(options.uniques);
   const checks = normalizeChecks(options.checks);
+  const softDelete = normalizeSoftDelete(options.softDelete);
 
-  return {
+  const ir = {
     schemaName,
     tableName,
     qualifiedName,
@@ -61,6 +68,14 @@ function buildIR(tableName, options) {
       autoGeneratedRelations
     }
   };
+
+  // Optional block: only attach when declared so SDF tanpa softDelete tetap byte-identik
+  // dengan IR baseline (backward-compat, R1 anti-magic — tidak menambah key diam-diam).
+  if (softDelete !== undefined) {
+    ir.softDelete = softDelete;
+  }
+
+  return ir;
 }
 
 function validateInputs(tableName, options) {
@@ -94,6 +109,41 @@ function validateInputs(tableName, options) {
   if (options.schema !== undefined && options.schema !== null && typeof options.schema !== 'string') {
     throw new Error(`Table '${tableName}': options.schema must be a string or null`);
   }
+  if (options.softDelete !== undefined) {
+    if (!isPlainObject(options.softDelete)) {
+      throw new Error(`Table '${tableName}': options.softDelete must be a plain object`);
+    }
+    if (typeof options.softDelete.enabled !== 'boolean') {
+      throw new Error(`Table '${tableName}': options.softDelete.enabled must be a boolean`);
+    }
+    // R1 (strict): tolak key tak dikenal di level blok `softDelete` (selain whitelist),
+    // alih-alih membiarkan normalizeSoftDelete membuangnya diam-diam.
+    for (const key of Object.keys(options.softDelete)) {
+      if (!SOFT_DELETE_ALLOWED_KEYS.has(key)) {
+        throw new Error(unknownSoftDeleteKeyError(tableName, key));
+      }
+    }
+    if (options.softDelete.reusable !== undefined) {
+      if (!Array.isArray(options.softDelete.reusable)) {
+        throw new Error(`Table '${tableName}': options.softDelete.reusable must be an array`);
+      }
+      for (let i = 0; i < options.softDelete.reusable.length; i++) {
+        const entry = options.softDelete.reusable[i];
+        if (!isPlainObject(entry)) {
+          throw new Error(`Table '${tableName}': options.softDelete.reusable[${i}] must be a plain object`);
+        }
+        // R1 (strict): tiap entri reusable hanya boleh `field` dan `length`.
+        for (const key of Object.keys(entry)) {
+          if (!SOFT_DELETE_REUSABLE_ALLOWED_KEYS.has(key)) {
+            throw new Error(
+              `Table '${tableName}': options.softDelete.reusable[${i}] has unknown key '${key}'; ` +
+              `only 'field' and 'length' are allowed.`
+            );
+          }
+        }
+      }
+    }
+  }
 }
 
 function parseField(shorthand, fieldName, tableName) {
@@ -275,6 +325,39 @@ function normalizeChecks(input) {
   return result;
 }
 
+// Pesan ERROR unknown-key di level blok `softDelete`. Untuk `visibility` diberi
+// petunjuk khusus: itu config endpoint di RDF/payload (R13/R15), bukan SDF, supaya
+// developer memindahkannya, bukan sekadar menghapus.
+function unknownSoftDeleteKeyError(tableName, key) {
+  let msg =
+    `Table '${tableName}': options.softDelete has unknown key '${key}'; ` +
+    `only 'enabled' and 'reusable' are allowed.`;
+  if (key === 'visibility') {
+    msg +=
+      ` 'visibility' is an endpoint configuration declared in the RDF/payload ` +
+      `(one of active_only/deleted_only/include_deleted, see R13/R15), not in the SDF; ` +
+      `move it to the payload's softDelete block instead of declaring it here.`;
+  }
+  return msg;
+}
+
+function normalizeSoftDelete(input) {
+  if (input === undefined) return undefined;
+  // validateInputs sudah menjamin: input plain object, enabled boolean,
+  // reusable (bila ada) array of object, DAN tidak ada key tak dikenal — baik di
+  // level blok (hanya enabled/reusable) maupun di tiap entri reusable (hanya
+  // field/length). Jadi key seperti `visibility` (R13/R15, milik RDF) sudah ditolak
+  // ERROR di validateInputs, bukan di-drop diam-diam di sini (R1, anti-magic).
+  // Di sini hanya normalisasi minimal: simpan enabled apa adanya, dan proyeksikan
+  // tiap entri reusable ke { field, length }. Validasi semantik (kolom ada, tipe,
+  // unique, panjang) ditegakkan di validateSoftDelete.
+  const out = { enabled: input.enabled };
+  if (input.reusable !== undefined) {
+    out.reusable = input.reusable.map((entry) => ({ field: entry.field, length: entry.length }));
+  }
+  return out;
+}
+
 function isPlainObject(v) {
   return v !== null && typeof v === 'object' && !Array.isArray(v);
 }

package/generators/lib/dbschema-kit/schema-printer.js

@@ -56,6 +56,10 @@ function serialize(ir, options) {
         sections.push(serializeRelationsSection(explicitRelations));
     }
 
+    if (ir.softDelete && ir.softDelete.enabled === true) {
+        sections.push(serializeSoftDeleteSection(ir.softDelete));
+    }
+
     const header = [
         "'use strict';",
         '',
@@ -319,6 +323,22 @@ function formatLiteralValue(v) {
     return String(v);
 }
 
+// ─────────────────────────────────────────────────────────────
+// softDelete section (R6 reverse)
+// ─────────────────────────────────────────────────────────────
+
+// Introspect hanya menurunkan `enabled` (R8 poin 2): `reusable`/base-length adalah
+// intent developer yang tidak tersimpan di database, jadi tidak diturunkan. SDF hasil
+// introspect cukup `softDelete: { enabled: true }` (re-load tetap valid: ketiga kolom
+// ada + enabled true memenuhi invariant R3/R5).
+function serializeSoftDeleteSection(softDelete) {
+    return [
+        '  softDelete: {',
+        '    enabled: true',
+        '  }'
+    ];
+}
+
 // ─────────────────────────────────────────────────────────────
 // relations section
 // ─────────────────────────────────────────────────────────────

package/generators/lib/dbschema-kit/soft-delete-constants.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const { generateConstraintName } = require('./naming');
+
+// Soft-delete (Fase 1) — sumber kebenaran tunggal untuk nama kolom soft-delete dan
+// panjang suffix mutasi. Dipakai bersama oleh:
+//   - validator SDF (validator/schema-validator.js) untuk invariant R3/R5/R7/R9,
+//   - emitter DDL forward (emitters/create-table.js CHECK konsistensi R8,
+//     emitters/create-index.js partial index R10/R11), dan
+//   - jalur reverse Phase 03 (introspect-mapper.js deteksi R6, diff-engine no-false-drift)
+//     untuk mengenali CHECK soft-delete lewat nama deterministik yang sama.
+// supaya tidak ada duplikat nama kolom atau angka suffix yang harus dijaga sinkron
+// di banyak tempat.
+//
+// Catatan scope: konstanta whitelist input SDF (`SOFT_DELETE_ALLOWED_KEYS` dkk. di
+// ir-builder.js) sengaja TIDAK dipindah ke sini. Itu domain parsing input (key apa
+// yang boleh ditulis di blok `softDelete`), beda concern dari nama kolom fisik DDL.
+
+// Tiga kolom soft-delete bernama tetap (R3) dengan kontrak tipe kaku (R5).
+const IS_DELETED_COLUMN = 'is_deleted';
+const DELETED_AT_COLUMN = 'deleted_at';
+const DELETED_BY_COLUMN = 'deleted_by';
+
+// Urutan array adalah urutan kanonik kolom: is_deleted, deleted_at, deleted_by.
+const SOFT_DELETE_COLUMNS = [IS_DELETED_COLUMN, DELETED_AT_COLUMN, DELETED_BY_COLUMN];
+
+// Kontrak tipe logical tiga kolom soft-delete (R5). Dipakai deteksi introspect
+// (reverse, R6) untuk memverifikasi tipe kolom benar sebelum mengakui sebuah tabel
+// sebagai soft-delete. Validator SDF (schema-validator.js) memegang kontrak yang sama
+// di sisi forward; keduanya WAJIB tetap identik (R5 fixed).
+const SOFT_DELETE_COLUMN_TYPES = {
+  [IS_DELETED_COLUMN]: 'boolean',
+  [DELETED_AT_COLUMN]: 'timestamp',
+  [DELETED_BY_COLUMN]: 'string'
+};
+
+// Suffix mutasi reuse '{code}##{uuidv7}' = '##' (2) + uuidv7 (36) = 38 char (R7).
+const SOFT_DELETE_SUFFIX_LENGTH = 38;
+
+// Suffix nama CHECK konsistensi soft-delete (R8). HARUS identik dengan emitter forward
+// Phase 02 (emitters/create-table.js memakai literal yang sama) agar reverse-matching
+// nama-based di Phase 03 mengenali CHECK yang sama tanpa false drift. Konsistensi
+// nama-derivation antara emit (forward) dan match (reverse) adalah kunci no-false-drift.
+const SOFT_DELETE_CHECK_SUFFIX = 'soft_delete_consistency';
+
+// Dialect yang didukung soft-delete pada Fase 1. CHECK konsistensi memakai boolean
+// native (`= TRUE`/`= FALSE`) dan index non-unique memakai partial index; keduanya
+// adalah bentuk PostgreSQL. Adaptasi VARCHAR 'true'/'false' dan plain index untuk
+// dialect lain ditunda ke fase multi-database.
+const SOFT_DELETE_PHASE1_DIALECT = 'postgres';
+
+// Predikat tunggal kehadiran soft-delete aktif pada IR. Blok `softDelete` bersifat
+// optional di IR (hanya di-attach bila dideklarasikan, lihat ir-builder), jadi guard
+// `softDelete && softDelete.enabled === true` dipakai konsisten di semua emitter agar
+// emisi soft-delete benar-benar guarded (backward-compat byte-identik baseline).
+function isSoftDeleteEnabled(ir) {
+  return !!(ir && ir.softDelete && ir.softDelete.enabled === true);
+}
+
+// Guard Fase 1 PostgreSQL-only. Bila soft-delete aktif tetapi dialect bukan PostgreSQL,
+// lempar ERROR jelas alih-alih meng-emit DDL salah diam-diam (bentuk VARCHAR boolean /
+// plain index). Dipakai oleh emitter CHECK (create-table) dan partial index (create-index)
+// supaya tiap emitter aman dipanggil mandiri (test maupun jalur generateDDL).
+function assertSoftDeletePostgresOnly(ir, dialect) {
+  if (!isSoftDeleteEnabled(ir)) return;
+  if (dialect && dialect.name === SOFT_DELETE_PHASE1_DIALECT) return;
+  const label = (ir && (ir.qualifiedName || ir.tableName)) || '<unknown>';
+  const dialectName = dialect && dialect.name ? dialect.name : '<unknown>';
+  throw new Error(
+    `Table '${label}': soft-delete is PostgreSQL-only in Phase 1, ` +
+    `but the active dialect is '${dialectName}'. ` +
+    `Remove the softDelete block or generate DDL for PostgreSQL.`
+  );
+}
+
+// Derivasi nama CHECK konsistensi soft-delete, identik dengan emitter forward Phase 02
+// (emitters/create-table.js emitSoftDeleteCheck). `maxIdentifierLength` WAJIB sama dengan
+// yang dipakai emitter (`dialect.maxIdentifierLength`, PostgreSQL = 63) agar tabel bernama
+// panjang yang ter-truncate menghasilkan nama identik di kedua arah (tidak false drift).
+function softDeleteCheckName(tableName, maxIdentifierLength) {
+  return generateConstraintName('chk', tableName, SOFT_DELETE_CHECK_SUFFIX, maxIdentifierLength);
+}
+
+// Bangun rekomendasi SQL native PostgreSQL (R8) untuk menambahkan CHECK konsistensi
+// soft-delete. Dipakai pesan ERROR introspect (R6) saat tiga kolom lengkap & bertipe
+// benar tetapi CHECK hilang. Bentuk persis mengikuti plan master R8 (boolean native PG).
+function buildSoftDeleteCheckSql(tableName, maxIdentifierLength) {
+  const name = softDeleteCheckName(tableName, maxIdentifierLength);
+  return (
+    `ALTER TABLE ${tableName} ADD CONSTRAINT ${name}\n` +
+    `    CHECK (\n` +
+    `        (${IS_DELETED_COLUMN} = TRUE  AND ${DELETED_AT_COLUMN} IS NOT NULL AND ${DELETED_BY_COLUMN} IS NOT NULL)\n` +
+    `     OR (${IS_DELETED_COLUMN} = FALSE AND ${DELETED_AT_COLUMN} IS NULL     AND ${DELETED_BY_COLUMN} IS NULL)\n` +
+    `    );`
+  );
+}
+
+module.exports = {
+  IS_DELETED_COLUMN,
+  DELETED_AT_COLUMN,
+  DELETED_BY_COLUMN,
+  SOFT_DELETE_COLUMNS,
+  SOFT_DELETE_COLUMN_TYPES,
+  SOFT_DELETE_SUFFIX_LENGTH,
+  SOFT_DELETE_CHECK_SUFFIX,
+  SOFT_DELETE_PHASE1_DIALECT,
+  isSoftDeleteEnabled,
+  assertSoftDeletePostgresOnly,
+  softDeleteCheckName,
+  buildSoftDeleteCheckSql
+};