@restforgejs/platform 4.1.1 → 4.2.8

package/generators/lib/payload/endpoint-schema-validator.js

@@ -0,0 +1,171 @@
+'use strict';
+
+/**
+ * Endpoint Schema Validator
+ *
+ * Orchestrator untuk validasi schema database saat `endpoint create` dijalankan.
+ * Module ini:
+ *   1. Resolve --config file (via config-resolver)
+ *   2. Load config + connect ke database (via DatabaseIntrospector)
+ *   3. Compare payload-vs-database menggunakan compareSchemaStrict
+ *   4. Map hasil ke exit-code semantics:
+ *        - clean schema -> return { status: 'ok' }
+ *        - drift detected -> throw error dengan exitCode=1 + formatted report
+ *        - connection fail -> throw error dengan exitCode=3
+ *        - usage error -> throw error dengan exitCode=2 (di-handle caller via validateContract)
+ *
+ * Module ini sengaja decoupled dari PayloadGenerator agar tidak ikut menjalankan
+ * payload regenerate/sync flow.
+ *
+ * @module lib/payload/endpoint-schema-validator
+ */
+
+const { DatabaseIntrospector } = require('../utils/database-introspector');
+const { resolveConfig, printDefaultConfigWarning } = require('../utils/config-resolver');
+const { compareSchemaStrict, formatDriftReport } = require('./schema-diff');
+
+/**
+ * Buat Error object dengan property `exitCode` agar cli-entry dapat
+ * forward exit code spesifik.
+ *
+ * @param {string} message
+ * @param {number} exitCode
+ * @returns {Error}
+ */
+function createExitError(message, exitCode) {
+    const err = new Error(message);
+    err.exitCode = exitCode;
+    err.isSchemaValidationError = true;
+    return err;
+}
+
+/**
+ * Jalankan validasi schema untuk satu payload + table sebelum codegen.
+ *
+ * @param {Object} options
+ * @param {Object} options.payload - Processed payload object (harus punya tableName)
+ * @param {string} options.payloadFileName - Nama file payload untuk pesan error
+ * @param {string} options.configArg - Nilai flag --config dari CLI
+ * @param {boolean} options.skipSchemaCheck - true bila --skip-schema-check di-set
+ * @param {string} [options.workingDir] - cwd, default process.cwd()
+ * @param {Function} [options.IntrospectorClass] - Override untuk testing
+ * @returns {Promise<{
+ *   status: 'ok' | 'skipped',
+ *   reason?: string,
+ *   columnsChecked?: number
+ * }>}
+ * @throws {Error} Dengan property exitCode (1=drift, 2=usage, 3=connection)
+ */
+async function validateEndpointSchema(options) {
+    const {
+        payload,
+        payloadFileName,
+        configArg,
+        skipSchemaCheck,
+        workingDir,
+        IntrospectorClass
+    } = options;
+
+    if (!payload || !payload.tableName) {
+        throw createExitError('Payload missing tableName — cannot run schema validation', 2);
+    }
+
+    if (skipSchemaCheck) {
+        return { status: 'skipped', reason: '--skip-schema-check active' };
+    }
+
+    const resolved = resolveConfig(configArg, workingDir || process.cwd());
+    if (!resolved) {
+        const lines = [
+            'Error: --config is required for schema validation',
+            'Usage: npx restforge endpoint create --project=<P> --name=<N> --payload=<F> --config=<ENV> [--force=true] [--skip-schema-check]'
+        ];
+        throw createExitError(lines.join('\n'), 2);
+    }
+
+    if (resolved.source === 'default') {
+        printDefaultConfigWarning(resolved.defaultName);
+    }
+
+    const IntroCtor = IntrospectorClass || DatabaseIntrospector;
+    const db = new IntroCtor({ quiet: true });
+
+    const loaded = db.loadConfig(resolved.path);
+    if (!loaded) {
+        throw createExitError(
+            buildConnectionErrorMessage(`Cannot load config file: ${resolved.path}`),
+            3
+        );
+    }
+
+    let connected = false;
+    try {
+        connected = await db.connect();
+    } catch (e) {
+        try { await db.close(); } catch (_e) { /* ignore */ }
+        throw createExitError(
+            buildConnectionErrorMessage(e.message || String(e)),
+            3
+        );
+    }
+
+    if (!connected) {
+        try { await db.close(); } catch (_e) { /* ignore */ }
+        throw createExitError(
+            buildConnectionErrorMessage('database not reachable'),
+            3
+        );
+    }
+
+    let comparison;
+    try {
+        comparison = await compareSchemaStrict(payload, db);
+    } finally {
+        try { await db.close(); } catch (_e) { /* ignore */ }
+    }
+
+    if (comparison.status === 'error') {
+        const lines = [
+            'Schema Validation:',
+            `  [ERROR] ${comparison.summary}`,
+            '  Endpoint generation blocked.',
+            '',
+            '  Workarounds:',
+            '    1. Verify the table exists in the database',
+            '    2. Use --skip-schema-check to bypass validation (NOT recommended for production)'
+        ];
+        throw createExitError(lines.join('\n'), 3);
+    }
+
+    if (comparison.status === 'drift') {
+        const driftLines = formatDriftReport(comparison, {
+            payloadFileName,
+            tableName: payload.tableName
+        });
+        const lines = ['Schema Validation:', ...driftLines, '', 'Endpoint generation blocked due to schema drift'];
+        throw createExitError(lines.join('\n'), 1);
+    }
+
+    return {
+        status: 'ok',
+        columnsChecked: comparison.totalColumnsChecked || 0
+    };
+}
+
+function buildConnectionErrorMessage(reason) {
+    const lines = [
+        'Schema Validation:',
+        `  [ERROR] Cannot connect to database: ${reason}`,
+        '  Endpoint generation blocked.',
+        '',
+        '  Workarounds:',
+        '    1. Verify db-connection.env is correct and database is reachable',
+        '    2. Use --skip-schema-check to bypass validation (NOT recommended for production)'
+    ];
+    return lines.join('\n');
+}
+
+module.exports = {
+    validateEndpointSchema,
+    createExitError
+};

package/generators/lib/payload/payload-runner.js

@@ -27,17 +27,21 @@ const path = require('path');
 
 const { DatabaseIntrospector, loadDriver } = require('../utils/database-introspector');
 const { resolveConfig, printDefaultConfigWarning } = require('../utils/config-resolver');
+const {
+    DEFAULT_AUDIT_COLUMNS,
+    detectAuditAlignment
+} = require('../utils/audit-columns');
+const { compareSchemaStrict } = require('./schema-diff');
 
 // Kolom audit yang di-handle otomatis oleh RESTForge runtime (base-model).
-// Kolom ini di-exclude dari payload hasil generate karena nilainya selalu
-// di-set runtime saat create/update. User tetap bisa menambahkan secara manual
-// di file payload jika memang diperlukan untuk scenario khusus.
+// Konstanta dipakai dari shared util agar source-of-truth tunggal lintas
+// modul (sync, validate, endpoint create). Kolom ini di-exclude dari payload
+// hasil generate karena nilainya selalu di-set runtime saat create/update.
 //
 // Bila tabel tidak memiliki satupun kolom dari list ini, generator otomatis
 // menyertakan "auditColumns": false di payload supaya template generator
 // men-set this.auditColumns = null di model. Tanpa flag ini, runtime akan
 // mencoba inject kolom audit ke INSERT dan menyebabkan error 500.
-const DEFAULT_EXCLUDED_COLUMNS = ['created_at', 'created_by', 'updated_at', 'updated_by'];
 
 // Deteksi environment - Bun compiled binary atau Node.js/Bun script
 const isBun = typeof Bun !== 'undefined';
@@ -461,6 +465,9 @@ class PayloadGenerator {
 
         // Drift, error, atau target tidak ditemukan -> throw (exit 1 via cli-entry.js).
         // Semantik "action required" untuk MCP/LSP integration.
+        // Marked silent karena verdict + summary sudah di-print oleh runValidate/
+        // runDiff/runSync; pesan "Error: Payload schema action required: ..."
+        // hanya menambah noise di stderr untuk human user.
         const hasDrift = (result?.drift ?? 0) > 0;
         const hasError = (result?.error ?? 0) > 0;
         const targetMissing = targetTable && (result?.total ?? 0) === 0;
@@ -470,7 +477,10 @@ class PayloadGenerator {
           if (hasDrift) reasons.push(`drift=${result.drift}`);
           if (hasError) reasons.push(`error=${result.error}`);
           if (targetMissing) reasons.push(`target '${targetTable}' not found`);
-          throw new Error(`Payload schema action required: ${reasons.join(', ')}`);
+          const err = new Error(`Payload schema action required: ${reasons.join(', ')}`);
+          err.silent = true;
+          err.exitCode = 1;
+          throw err;
         }
 
         return;
@@ -534,8 +544,8 @@ class PayloadGenerator {
       const columns = await this.db.getColumns(args.table);
       if (columns.length > 0) {
         // Filter kolom audit yang di-handle otomatis oleh runtime.
-        const excludedPresent = columns.filter(col => DEFAULT_EXCLUDED_COLUMNS.includes(col));
-        payloadData.fieldName = columns.filter(col => !DEFAULT_EXCLUDED_COLUMNS.includes(col));
+        const excludedPresent = columns.filter(col => DEFAULT_AUDIT_COLUMNS.includes(col));
+        payloadData.fieldName = columns.filter(col => !DEFAULT_AUDIT_COLUMNS.includes(col));
         if (excludedPresent.length > 0) {
           console.log(`Auto-managed columns excluded: ${excludedPresent.join(', ')}`);
         } else {
@@ -639,86 +649,6 @@ class SchemaValidator {
     this.outputDir = outputDir;
   }
 
-  /**
-   * Normalisasi tipe data database ke kategori umum untuk perbandingan.
-   * Tipe database bervariasi antar engine, fungsi ini memetakan ke nama yang konsisten.
-   * @param {string} dataType - Tipe data dari information_schema
-   * @param {string} udtName - UDT name (PostgreSQL specific)
-   * @param {Object} col - Full column info object
-   * @returns {string} Normalized type string
-   */
-  normalizeType(dataType, udtName, col) {
-    const dt = (dataType || '').toLowerCase();
-    const udt = (udtName || '').toLowerCase();
-
-    // UUID
-    if (dt === 'uuid' || udt === 'uuid') return 'uuid';
-
-    // Boolean
-    if (dt === 'boolean' || udt === 'bool') return 'boolean';
-
-    // Integer family
-    if (['integer', 'bigint', 'smallint', 'serial', 'bigserial', 'smallserial',
-         'int', 'tinyint', 'mediumint'].includes(dt) ||
-        ['int4', 'int8', 'int2', 'serial4', 'serial8', 'serial2'].includes(udt)) {
-      return 'integer';
-    }
-
-    // Numeric/decimal family
-    if (['numeric', 'decimal', 'real', 'double precision', 'float', 'double'].includes(dt) ||
-        ['numeric', 'float4', 'float8'].includes(udt)) {
-      const precision = col && col.numeric_precision ? `(${col.numeric_precision}` : '';
-      const scale = col && col.numeric_scale !== null && col.numeric_scale !== undefined
-        ? `,${col.numeric_scale})` : precision ? ')' : '';
-      return precision ? `numeric${precision}${scale}` : 'numeric';
-    }
-
-    // Text / varchar family
-    if (['character varying', 'varchar', 'varchar2', 'nvarchar2', 'nvarchar'].includes(dt)) {
-      const len = col && col.character_maximum_length ? `(${col.character_maximum_length})` : '';
-      return `varchar${len}`;
-    }
-    if (['text', 'clob', 'nclob', 'longtext', 'mediumtext', 'tinytext'].includes(dt)) return 'text';
-    if (['char', 'character', 'nchar'].includes(dt)) {
-      const len = col && col.character_maximum_length ? `(${col.character_maximum_length})` : '';
-      return `char${len}`;
-    }
-
-    // Date/time family
-    if (dt === 'date') return 'date';
-    if (dt === 'datetime') return 'timestamp';
-    if (dt.startsWith('timestamp')) return 'timestamp';
-    if (dt.startsWith('time')) return 'time';
-
-    // JSON
-    if (['json', 'jsonb'].includes(dt) || ['json', 'jsonb'].includes(udt)) return 'json';
-
-    // Fallback
-    return dt || 'unknown';
-  }
-
-  /**
-   * Normalisasi tipe dari fieldValidation payload ke kategori yang sama.
-   * @param {Object} validation - Object dari array fieldValidation
-   * @returns {string} Normalized type string
-   */
-  normalizePayloadValidationType(validation) {
-    if (!validation) return null;
-    const t = (validation.type || '').toLowerCase();
-    switch (t) {
-      case 'uuid': return 'uuid';
-      case 'integer': return 'integer';
-      case 'number': return 'numeric';
-      case 'boolean': return 'boolean';
-      case 'date': return 'date';
-      case 'datetime': return 'timestamp';
-      case 'string': return 'varchar';
-      case 'json':
-      case 'array': return 'json';
-      default: return t || null;
-    }
-  }
-
   /**
    * Cari semua file payload JSON di outputDir.
    * @returns {Array<{filePath: string, fileName: string, payload: Object}>}
@@ -781,120 +711,18 @@ class SchemaValidator {
     return match || null;
   }
 
-  /**
-   * Bandingkan satu payload dengan schema database aktual.
-   * @param {Object} payload - Payload JSON object
-   * @returns {Promise<Object>} Comparison result
-   */
-  async comparePayloadWithDatabase(payload) {
-    const tableName = payload.tableName;
-    const result = {
-      tableName,
-      status: 'ok', // ok, drift, error
-      added: [],    // kolom baru di database, tidak ada di payload
-      removed: [],  // ada di payload, tidak ada di database
-      typeChanges: [], // tipe data berubah
-      nullabilityChanges: [], // nullable berubah
-      summary: ''
-    };
-
-    // Cek apakah table masih ada di database
-    const dbColumns = await this.db.getDetailedColumnInfo(tableName);
-    if (dbColumns.length === 0) {
-      result.status = 'error';
-      result.summary = `Table "${tableName}" not found in database`;
-      return result;
-    }
-
-    // Build map dari database columns
-    const dbColumnMap = {};
-    for (const col of dbColumns) {
-      dbColumnMap[col.column_name] = col;
-    }
-
-    // Build map dari payload fieldValidation
-    const payloadValidationMap = {};
-    if (payload.fieldValidation) {
-      for (const fv of payload.fieldValidation) {
-        payloadValidationMap[fv.name] = fv;
-      }
-    }
-
-    const payloadFields = payload.fieldName || [];
-    const dbColumnNames = dbColumns.map(c => c.column_name);
-
-    // Detect kolom baru di database (tidak ada di payload).
-    // Kolom audit default (DEFAULT_EXCLUDED_COLUMNS) yang tidak dicantumkan
-    // user di payload akan di-skip karena memang sengaja di-exclude.
-    for (const dbCol of dbColumns) {
-      if (!payloadFields.includes(dbCol.column_name)) {
-        if (DEFAULT_EXCLUDED_COLUMNS.includes(dbCol.column_name)) continue;
-
-        const normalizedType = this.normalizeType(dbCol.data_type, dbCol.udt_name, dbCol);
-        result.added.push({
-          column: dbCol.column_name,
-          type: normalizedType,
-          nullable: dbCol.is_nullable === 'YES'
-        });
-      }
-    }
-
-    // Detect kolom yang dihapus dari database (masih ada di payload)
-    for (const field of payloadFields) {
-      if (!dbColumnMap[field]) {
-        result.removed.push({
-          column: field
-        });
-      }
-    }
-
-    // Detect perubahan tipe data (hanya untuk field yang ada di kedua sisi)
-    for (const field of payloadFields) {
-      const dbCol = dbColumnMap[field];
-      if (!dbCol) continue;
-
-      const dbType = this.normalizeType(dbCol.data_type, dbCol.udt_name, dbCol);
-      const payloadValidation = payloadValidationMap[field];
-
-      if (payloadValidation) {
-        const payloadType = this.normalizePayloadValidationType(payloadValidation);
-        // Perbandingan menggunakan base type (tanpa size detail)
-        const dbBaseType = dbType.replace(/\(.*\)/, '');
-        const payloadBaseType = payloadType ? payloadType.replace(/\(.*\)/, '') : null;
-
-        if (payloadBaseType && dbBaseType !== payloadBaseType) {
-          result.typeChanges.push({
-            column: field,
-            payloadType: payloadType,
-            databaseType: dbType
-          });
-        }
-      }
-    }
-
-    // Determine overall status
-    if (result.added.length > 0 || result.removed.length > 0 || result.typeChanges.length > 0) {
-      result.status = 'drift';
-    }
-
-    // Build summary
-    const parts = [];
-    if (result.added.length > 0) parts.push(`${result.added.length} new column(s) in database`);
-    if (result.removed.length > 0) parts.push(`${result.removed.length} column(s) missing from database`);
-    if (result.typeChanges.length > 0) parts.push(`${result.typeChanges.length} type change(s)`);
-    result.summary = parts.length > 0 ? parts.join(', ') : 'Schema is in sync';
-
-    return result;
-  }
-
   /**
    * Format hasil perbandingan ke output console.
-   * @param {Object} comparison - Hasil dari comparePayloadWithDatabase()
+   * Konsisten dengan `endpoint create` (audit-column-aware).
+   *
+   * @param {Object} comparison - Hasil dari compareSchemaStrict()
    * @param {string} fileName - Nama file payload
-   * @param {boolean} showDiffDetail - Tampilkan detail diff
+   * @param {boolean} showDiffDetail - Tampilkan detail per-column drift
    */
   printComparisonResult(comparison, fileName, showDiffDetail = false) {
-    const statusIcon = comparison.status === 'ok' ? '[OK]'
+    // Pad status icon ke lebar tetap 7 char ([DRIFT]/[ERROR]) supaya kolom
+    // fileName tampil rata antar baris.
+    const statusIcon = comparison.status === 'ok' ? '[OK]   '
       : comparison.status === 'drift' ? '[DRIFT]'
       : '[ERROR]';
 
@@ -915,24 +743,29 @@ class SchemaValidator {
     // Status: drift
     console.log(`         ${comparison.summary}`);
 
-    if (showDiffDetail) {
-      if (comparison.added.length > 0) {
-        for (const col of comparison.added) {
-          const nullable = col.nullable ? ', nullable' : ', not null';
-          console.log(`         [+] ${col.column}  (${col.type}${nullable})`);
-        }
+    if (!showDiffDetail) return;
+
+    if (Array.isArray(comparison.removed)) {
+      for (const item of comparison.removed) {
+        console.log(`         [-] ${item.column}    (in payload, not in database)`);
       }
-      if (comparison.removed.length > 0) {
-        for (const col of comparison.removed) {
-          console.log(`         [-] ${col.column}`);
-        }
+    }
+    if (Array.isArray(comparison.typeChanges)) {
+      for (const item of comparison.typeChanges) {
+        console.log(`         [~] ${item.column}    (type: ${item.payloadType} -> ${item.databaseType})`);
       }
-      if (comparison.typeChanges.length > 0) {
-        for (const col of comparison.typeChanges) {
-          console.log(`         [~] ${col.column}: ${col.payloadType} -> ${col.databaseType}`);
-        }
+    }
+    if (Array.isArray(comparison.added)) {
+      for (const item of comparison.added) {
+        const nullable = item.nullable ? ', nullable' : ', not null';
+        console.log(`         [+] ${item.column}    (${item.type}${nullable}) (in database, not in payload)`);
       }
     }
+    if (Array.isArray(comparison.auditMissing) && comparison.auditMissing.length > 0) {
+      const cols = comparison.auditMissing.join(', ');
+      console.log(`         [+] ${cols}`);
+      console.log('             (required by auditColumns=true, not in database)');
+    }
   }
 
   /**
@@ -976,7 +809,7 @@ class SchemaValidator {
     let ok = 0, drift = 0, error = 0;
 
     for (const { fileName, payload } of payloads) {
-      const comparison = await this.comparePayloadWithDatabase(payload);
+      const comparison = await compareSchemaStrict(payload, this.db);
       results.push({ fileName, comparison });
       this.printComparisonResult(comparison, fileName, false);
 
@@ -1047,7 +880,7 @@ class SchemaValidator {
       console.log('-'.repeat(60));
       console.log();
 
-      const comparison = await this.comparePayloadWithDatabase(payload);
+      const comparison = await compareSchemaStrict(payload, this.db);
       results.push({ fileName, comparison });
       this.printComparisonResult(comparison, fileName, true);
       console.log();
@@ -1154,7 +987,7 @@ class SchemaValidator {
     let synced = 0, skipped = 0, errorCount = 0;
 
     for (const { filePath, fileName, payload } of payloads) {
-      const comparison = await this.comparePayloadWithDatabase(payload);
+      const comparison = await compareSchemaStrict(payload, this.db);
 
       if (comparison.status === 'error') {
         console.log(`  [ERROR]   ${fileName} - ${comparison.summary}`);
@@ -1168,15 +1001,16 @@ class SchemaValidator {
         continue;
       }
 
-      // Status: drift - perlu sync
-      // 1. Archive file lama
+      // Status: drift (termasuk audit drift) — archive + regenerate.
       const archivePath = this.archiveFile(filePath);
       const archiveName = path.basename(archivePath);
       console.log(`  [ARCHIVE] ${fileName} -> ${archiveName}`);
 
-      // 2. Re-generate payload dari database
+      // Re-generate payload dari database. regeneratePayload menerapkan audit
+      // columns resolution secara internal (set auditColumns: false bila DB
+      // tidak punya kolom audit standar).
       try {
-        const updatedPayload = await this.regeneratePayload(payload, comparison);
+        const updatedPayload = await this.regeneratePayload(payload, comparison, { fileName });
         fs.writeFileSync(filePath, JSON.stringify(updatedPayload, null, 4), 'utf8');
         console.log(`  [SYNCED]  ${fileName} - ${comparison.summary}`);
         synced++;
@@ -1205,12 +1039,17 @@ class SchemaValidator {
   /**
    * Regenerate payload berdasarkan perubahan yang terdeteksi.
    * Mempertahankan konfigurasi payload lama (action, filters, dll),
-   * hanya update fieldName, fieldValidation, dateTimeFields, dan query.
+   * hanya update fieldName, fieldValidation, dateTimeFields, query, dan
+   * (sejak Phase 03) field `auditColumns` bila terjadi misalignment dengan
+   * tabel database.
+   *
    * @param {Object} oldPayload - Payload JSON lama
    * @param {Object} comparison - Hasil comparePayloadWithDatabase
+   * @param {Object} [options]
+   * @param {string} [options.fileName] - Nama file payload untuk pesan log
    * @returns {Promise<Object>} Updated payload
    */
-  async regeneratePayload(oldPayload, comparison) {
+  async regeneratePayload(oldPayload, comparison, options = {}) {
     const tableName = oldPayload.tableName;
 
     // Ambil data terbaru dari database
@@ -1233,7 +1072,7 @@ class SchemaValidator {
     // Tambahkan field baru dari database, skip kolom audit default
     for (const col of dbColumns) {
       if (newFieldName.includes(col)) continue;
-      if (DEFAULT_EXCLUDED_COLUMNS.includes(col)) continue;
+      if (DEFAULT_AUDIT_COLUMNS.includes(col)) continue;
       newFieldName.push(col);
     }
 
@@ -1291,8 +1130,86 @@ class SchemaValidator {
       delete updatedPayload.fieldValidation;
     }
 
+    // Audit columns resolution (Phase 03):
+    // Pastikan field `auditColumns` di payload aligned dengan struktur tabel
+    // database. Logic ini mencegah inkonsistensi antara `payload sync` (yang
+    // sebelumnya tidak menyentuh auditColumns) dan `endpoint create` (yang
+    // sudah audit-column-aware sejak Phase 01).
+    this.resolveAuditColumnsForSync(updatedPayload, oldPayload, dbColumns, {
+      tableName,
+      fileName: options.fileName
+    });
+
     return updatedPayload;
   }
+
+  /**
+   * Resolve nilai `auditColumns` untuk payload hasil sync. Memutasi
+   * `updatedPayload` in-place.
+   *
+   * Aturan (lihat phase-03-audit-aware-sync.md):
+   *   - oldPayload.auditColumns === false/null -> preserve (no-op)
+   *   - oldPayload.auditColumns object form    -> warn, no auto-override
+   *   - oldPayload.auditColumns === true + DB tidak full audit -> override
+   *     ke false + warning ke stderr
+   *   - oldPayload.auditColumns tidak di-set (default true) + DB tidak full
+   *     audit -> set false + info message
+   *   - DB punya keempat kolom audit standar -> preserve apapun bentuknya
+   *
+   * "DB tidak full audit" mencakup `none` (tidak satupun kolom audit) dan
+   * `partial` (1-3 kolom audit). Partial di-treat sebagai incomplete: shape
+   * audit tidak lengkap, generator tidak bisa inject 4 kolom sambil sebagian
+   * tidak exist. Default strict yang aman.
+   *
+   * @param {Object} updatedPayload - Payload yang akan ditulis (mutated)
+   * @param {Object} oldPayload - Payload lama (untuk inspect state asli)
+   * @param {string[]} dbColumns - Daftar kolom database
+   * @param {Object} ctx
+   * @param {string} ctx.tableName - Nama table
+   * @param {string} [ctx.fileName] - Nama file payload untuk pesan log
+   * @returns {void}
+   */
+  resolveAuditColumnsForSync(updatedPayload, oldPayload, dbColumns, ctx) {
+    const tableName = ctx.tableName;
+    const fileLabel = ctx.fileName || `${tableName}.json`;
+    const alignment = detectAuditAlignment(dbColumns);
+    const hasField = Object.prototype.hasOwnProperty.call(oldPayload, 'auditColumns');
+    const value = hasField ? oldPayload.auditColumns : undefined;
+
+    // Case 1: explicit false/null -> preserve (no-op)
+    if (value === false || value === null) {
+      return;
+    }
+
+    // Case 2: object form (custom column mapping) -> warn, no auto-override
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      console.warn(
+        `[restforge] Custom auditColumns object detected for "${tableName}". ` +
+        'Cannot auto-resolve. Verify column names manually.'
+      );
+      return;
+    }
+
+    // Case 3: DB punya semua kolom audit -> preserve apa adanya
+    if (alignment.all) {
+      return;
+    }
+
+    // Case 4: DB tidak full audit (none atau partial) + payload default/true
+    // -> set updatedPayload.auditColumns = false
+    if (value === true) {
+      console.warn(
+        `[restforge] Resetting auditColumns: true -> false for table "${tableName}" ` +
+        'because audit columns missing in database'
+      );
+    } else {
+      console.log(
+        `[restforge] Set "auditColumns": false in ${fileLabel} ` +
+        'because audit columns missing in database'
+      );
+    }
+    updatedPayload.auditColumns = false;
+  }
 }
 
 module.exports = {