@restforgejs/platform 5.1.7 → 5.1.16

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

@@ -32,6 +32,18 @@ const {
     detectAuditAlignment
 } = require('../utils/audit-columns');
 const { compareSchemaStrict } = require('./schema-diff');
+const { loadSchemaPath } = require('../dbschema-kit/loader');
+const {
+    SOFT_DELETE_COLUMNS,
+    isSoftDeleteEnabled,
+    softDeleteCheckName
+} = require('../dbschema-kit/soft-delete-constants');
+const softDeleteDashboardGuard = require('../../../src/utils/soft-delete-dashboard-guard');
+
+// Panjang identifier maksimum PostgreSQL (Fase 1 PostgreSQL-only). Dipakai untuk
+// menderivasi nama CHECK soft-delete saat menentukan status parent-soft-delete pada
+// FK-awareness (R20), identik dengan emitter forward (Phase 02) + reverse (Phase 03).
+const POSTGRES_MAX_IDENTIFIER_LENGTH = 63;
 
 // Kolom audit yang di-handle otomatis oleh RESTForge runtime (base-model).
 // Konstanta dipakai dari shared util agar source-of-truth tunggal lintas
@@ -487,6 +499,579 @@ function applyIsActiveDefaultScope(payload, hasIsActive) {
   if (Object.keys(ds).length === 0) delete payload.defaultScope;
 }
 
+// ============================================================================
+// SOFT-DELETE DERIVATION (SDF -> RDF) — payload generate (R12/R13)
+// ============================================================================
+
+/**
+ * Cari IR model untuk sebuah tabel di dalam Map hasil loadSchemaPath().
+ *
+ * Strategi match deterministik:
+ *   1. Exact qualifiedName: `models.get(tableName)` (Map dikunci qualifiedName).
+ *   2. Bare name: cocokkan `model.tableName === <bare>` (schema prefix di-strip)
+ *      atau `model.qualifiedName === tableName`.
+ *
+ * Bila lebih dari satu model cocok dengan bare name (mis. tabel sama di dua schema),
+ * lempar ERROR ambiguous — pemanggil harus qualify dengan schema.table (R1, strict).
+ *
+ * @param {Map<string, Object>} models - hasil loadSchemaPath()
+ * @param {string} tableName - nama tabel (bare atau schema.table)
+ * @returns {Object|null} IR model atau null bila tidak ditemukan
+ */
+function findModelByTable(models, tableName) {
+  if (models.has(tableName)) return models.get(tableName);
+
+  const bare = String(tableName).split('.').pop();
+  const matches = [];
+  for (const model of models.values()) {
+    if (model.tableName === bare || model.qualifiedName === tableName) {
+      matches.push(model);
+    }
+  }
+
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    throw new Error(
+      `Table '${tableName}' is ambiguous in the SDF: ${matches.length} models match the bare ` +
+      `name '${bare}'. Qualify --table with the schema (schema.table) to disambiguate.`
+    );
+  }
+  return null;
+}
+
+/**
+ * Resolusi blok `softDelete` SDF untuk tabel yang terdeteksi punya kolom soft-delete
+ * di database (R12). Memuat SDF via `loadSchemaPath` (jalur identik dengan command
+ * `schema`), mencari IR tabel, lalu memastikan blok `softDelete` valid (enabled).
+ *
+ * Aturan ERROR (tabel R12) — soft-delete WAJIB punya SDF yang konsisten:
+ *   - `--schema-path` kosong               -> ERROR (tidak bisa menurunkan blok)
+ *   - SDF gagal di-muat / SDF tidak valid -> ERROR (loadSchemaPath menjalankan
+ *     validateSchema; SDF dengan softDelete invalid gagal di sini)
+ *   - tabel tidak ada di SDF               -> ERROR (SDF tidak ditemukan untuk tabel)
+ *   - tabel ada tapi tanpa softDelete valid-> ERROR (softDelete.enabled !== true)
+ *
+ * `schemaPath` adalah nilai flag `--schema-path` (default `"schema"`, selaras
+ * `data pull`/`data push`); di-resolve relatif cwd oleh `loadSchemaPath`. Tabel
+ * soft-delete tanpa `--schema-path` eksplisit memakai default `"schema"`; bila
+ * folder itu tidak ada, ERROR "failed to load SDF" mengarahkan ke `--schema-path`.
+ *
+ * Validasi semantik blok (R3/R5/R7/R9) sudah ditegakkan `validateSoftDelete` saat
+ * load, jadi blok yang dikembalikan di sini dijamin enabled + kolom lengkap + reusable
+ * memenuhi syarat panjang.
+ *
+ * @param {string} tableName - nama tabel target (dari --table)
+ * @param {string|null} schemaPath - nilai flag --schema-path
+ * @returns {{ enabled: true, reusable?: Array<{field: string, length: number}> }} blok softDelete IR
+ * @throws {Error} bila salah satu kondisi R12 ERROR terpenuhi
+ */
+function resolveSoftDeleteForTable(tableName, schemaPath) {
+  if (typeof schemaPath !== 'string' || schemaPath.trim() === '') {
+    throw new Error(
+      `Table '${tableName}' has soft-delete columns (${SOFT_DELETE_COLUMNS.join('/')}) but ` +
+      `--schema-path was not provided. payload generate must read the SDF to derive the softDelete ` +
+      `block of the RDF (base length is not stored in the database, R12/R13). ` +
+      `Re-run with --schema-path=<path-to-sdf-file-or-folder>.`
+    );
+  }
+
+  let models;
+  try {
+    models = loadSchemaPath(schemaPath);
+  } catch (err) {
+    throw new Error(
+      `Table '${tableName}': failed to load SDF from --schema-path='${schemaPath}': ${err.message}`
+    );
+  }
+
+  const ir = findModelByTable(models, tableName);
+  if (!ir) {
+    throw new Error(
+      `Table '${tableName}' has soft-delete columns but is not declared in the SDF at ` +
+      `'${schemaPath}'. Add the table (with a valid softDelete block) to the SDF, or remove ` +
+      `the soft-delete columns from the database (R12).`
+    );
+  }
+
+  if (!isSoftDeleteEnabled(ir)) {
+    throw new Error(
+      `Table '${tableName}' has soft-delete columns but its SDF declaration has no valid ` +
+      `softDelete block (softDelete.enabled !== true). Declare softDelete in the SDF to generate ` +
+      `a soft-delete RDF (R12).`
+    );
+  }
+
+  return ir.softDelete;
+}
+
+/**
+ * Turunkan blok `softDelete` RDF dari blok `softDelete` SDF, secara in-place pada
+ * `payload` (pola `applyIsActiveDefaultScope`). Dipanggil HANYA bila tabel terdeteksi
+ * soft-delete dan SDF sudah diresolusi valid (R12), jadi seluruh mutasi guarded oleh
+ * deteksi (backward-compat byte-identik baseline untuk tabel non-soft-delete, R13).
+ *
+ * Dua mutasi:
+ *   1. Set `payload.softDelete = { enabled, reusable, visibility }`. `enabled`+`reusable`
+ *      dari SDF; `visibility` default "active_only" (config endpoint, BUKAN turunan SDF —
+ *      developer ubah per-endpoint nanti, R13/R15). Urutan key tetap enabled→reusable→
+ *      visibility sesuai R13.
+ *   2. Override `fieldValidation[field].maxLength = base length` untuk tiap field reusable
+ *      (R13): batasi input user ke base sehingga `base + 38 = physical` pas tanpa overflow.
+ *      Default `generateFieldValidation` memakai character_maximum_length (physical 88);
+ *      di sinilah perilaku default di-override pasca-generate.
+ *
+ * Idempoten dan tidak menyentuh field lain di payload.
+ *
+ * @param {Object} payload - payloadData yang dimutasi
+ * @param {{ enabled: boolean, reusable?: Array<{field: string, length: number}> }} sdfSoftDelete
+ * @returns {void}
+ */
+function applySoftDeleteDerivation(payload, sdfSoftDelete) {
+  const reusable = Array.isArray(sdfSoftDelete && sdfSoftDelete.reusable)
+    ? sdfSoftDelete.reusable.map((entry) => ({ field: entry.field, length: entry.length }))
+    : [];
+
+  payload.softDelete = {
+    enabled: true,
+    reusable,
+    visibility: 'active_only'
+  };
+
+  // Override maxLength reusable -> base length (R13). Entry pasti ada: reusable field
+  // wajib unique string (R9) sehingga generateFieldValidation menghasilkan entry-nya.
+  if (Array.isArray(payload.fieldValidation)) {
+    for (const entry of reusable) {
+      const fv = payload.fieldValidation.find((f) => f && f.name === entry.field);
+      if (fv && fv.constraints && typeof fv.constraints === 'object') {
+        fv.constraints.maxLength = entry.length;
+      }
+    }
+  }
+}
+
+/**
+ * Checkpoint soft-delete dashboard (WARNING, non-blocking) untuk `payload generate`.
+ *
+ * Saat RDF tabel soft-delete baru ditulis, scan dashboard yang sudah ada di `payloadDir`
+ * terhadap registry soft-delete saat ini. `payload generate` TIDAK meregenerasi dashboard
+ * yang sudah ada, sehingga bila soft-delete baru diaktifkan pada sebuah tabel, module
+ * dashboard lama tetap memuat SQL bocor (ikut membaca baris is_deleted=true). Tiap
+ * pelanggaran di-emit sebagai peringatan menonjol yang menyebut dashboard + widget + tabel
+ * pemicu, plus penjelasan bahwa dashboard harus diperbaiki lalu diregenerasi manual.
+ *
+ * WAJIB non-blocking: tidak melempar error. Generate RDF tetap selesai sukses meski ada
+ * peringatan. Hard stop atas drift ini ada di checkpoint runtime `serve` (prompt terpisah).
+ * Logika difaktorkan ke fungsi module-level agar dapat di-unit-test dengan spy pada `warn`,
+ * tanpa menjalankan jalur generate penuh.
+ *
+ * @param {string} payloadDir - direktori payload (tempat dashboard + file SQL-nya)
+ * @param {(msg: string) => void} [warn=console.warn] - sink peringatan (diinjeksi untuk test)
+ * @returns {Array} daftar pelanggaran yang diperingatkan (untuk observabilitas/test)
+ */
+function warnSoftDeleteDashboardDrift(payloadDir, warn = console.warn) {
+  let violations;
+  try {
+    violations = softDeleteDashboardGuard.scanDashboardsForViolations(payloadDir);
+  } catch (_err) {
+    // Scanner best-effort: kegagalan tak terduga TIDAK boleh menggagalkan generate.
+    return [];
+  }
+
+  for (const v of violations) {
+    const queryContext = v.key === null ? '' : ` (query '${v.key}')`;
+    warn(
+      `WARNING [soft-delete] dashboard '${v.dashboard}'${queryContext}: ` +
+      `${softDeleteDashboardGuard.formatViolationMessage(v)} ` +
+      `This dashboard was NOT regenerated by 'payload generate' and its module still serves the ` +
+      `leaking query; fix the widget and regenerate the dashboard.`
+    );
+  }
+
+  return violations;
+}
+
+/**
+ * Tentukan apakah tabel parent (`refTable`) adalah tabel soft-delete (R20 FK-awareness).
+ * Reuse deteksi name-based Phase 03: parent diakui soft-delete bila (a) ketiga kolom
+ * soft-delete (is_deleted/deleted_at/deleted_by) ADA, dan (b) CHECK konsistensi bernama
+ * `softDeleteCheckName(refTable, 63)` ADA. CHECK adalah penanda otoritatif (di-emit hanya
+ * oleh `schema migrate` dari SDF soft-delete valid), sehingga kombinasi kolom + CHECK cukup
+ * pasti tanpa perlu mengecek tipe ulang. Konservatif: ketidakpastian apa pun (introspeksi
+ * gagal, method tak tersedia, dialect non-PG) → `false` (cek eksistensi parent saja, R20 fallback).
+ *
+ * @param {Object} db - DatabaseIntrospector instance
+ * @param {string} qualifiedRefTable - nama parent ter-qualify (schema.table bila ada schema)
+ * @param {string} refTableName - nama parent TANPA schema (untuk derivasi nama CHECK)
+ * @returns {Promise<boolean>}
+ */
+async function isParentSoftDelete(db, qualifiedRefTable, refTableName) {
+  try {
+    if (!db || typeof db.getColumns !== 'function' || typeof db.getCheckConstraints !== 'function') {
+      return false;
+    }
+    const cols = await db.getColumns(qualifiedRefTable);
+    const colSet = new Set((cols || []).map((c) => String(c).toLowerCase()));
+    const hasAllColumns = SOFT_DELETE_COLUMNS.every((c) => colSet.has(c));
+    if (!hasAllColumns) return false;
+
+    const checks = await db.getCheckConstraints(qualifiedRefTable);
+    const expectedName = softDeleteCheckName(refTableName, POSTGRES_MAX_IDENTIFIER_LENGTH);
+    return Array.isArray(checks) && checks.some((c) => c && c.name === expectedName);
+  } catch (err) {
+    return false;
+  }
+}
+
+/**
+ * Derivasi daftar cek FK untuk restore (R20 FK-awareness) dari introspeksi DB. Untuk tiap
+ * foreign key tabel yang di-restore, simpan kolom lokal, tabel + kolom parent, dan status
+ * parent-soft-delete. Dikonsumsi template (`generateSoftDeleteRestoreOverride`) untuk meng-emit
+ * cek parent: parentSoftDelete=true → parent wajib aktif (is_deleted=FALSE, 422 bila tidak);
+ * false → cek eksistensi parent saja (422 bila hilang).
+ *
+ * Sumber FK list = `db.getForeignKeys` (tersedia di payload generate; TIDAK tersedia di jalur
+ * model generator yang murni RDF→kode). Hasil di-persist top-level di RDF (`softDeleteFkChecks`),
+ * pola yang sama dengan `uniqueConstraints` (sama-sama derived dari introspeksi DB di generate
+ * time, dikonsumsi template di codegen). Konservatif: introspeksi gagal / tidak ada FK → [].
+ *
+ * @param {Object} db - DatabaseIntrospector instance
+ * @param {string} tableName - nama tabel yang di-restore
+ * @returns {Promise<Array<{columns:string[], refTable:string, refColumns:string[], parentSoftDelete:boolean}>>}
+ */
+async function deriveSoftDeleteFkChecks(db, tableName) {
+  if (!db || !db.pool || typeof db.getForeignKeys !== 'function') return [];
+
+  let foreignKeys;
+  try {
+    foreignKeys = await db.getForeignKeys(tableName);
+  } catch (err) {
+    return [];
+  }
+  if (!Array.isArray(foreignKeys) || foreignKeys.length === 0) return [];
+
+  const checks = [];
+  const parentCache = new Map();
+  for (const fk of foreignKeys) {
+    const ref = fk && fk.references;
+    if (!ref || !ref.table) continue;
+    const columns = Array.isArray(fk.columns) ? fk.columns.slice() : [];
+    const refColumns = Array.isArray(ref.columns) ? ref.columns.slice() : [];
+    if (columns.length === 0 || refColumns.length === 0 || columns.length !== refColumns.length) {
+      continue;
+    }
+    const qualifiedRefTable = ref.schema ? `${ref.schema}.${ref.table}` : ref.table;
+
+    let parentSoftDelete;
+    if (parentCache.has(qualifiedRefTable)) {
+      parentSoftDelete = parentCache.get(qualifiedRefTable);
+    } else {
+      parentSoftDelete = await isParentSoftDelete(db, qualifiedRefTable, ref.table);
+      parentCache.set(qualifiedRefTable, parentSoftDelete);
+    }
+
+    checks.push({ columns, refTable: qualifiedRefTable, refColumns, parentSoftDelete });
+  }
+  return checks;
+}
+
+// ============================================================================
+// FK-SD-4 REGISTRY DERIVATION (SDF scan -> RDF) — Fase 1.5 FK-aware soft-delete
+// ============================================================================
+//
+// Menurunkan dua field RDF top-level baru saat `payload generate`, fondasi data untuk
+// FK-SD-1 (forward block), FK-SD-2 (restrict), FK-SD-3 (cascade). Phase ini TIDAK
+// mengubah behavior handler; hanya derivasi + persist metadata.
+//
+// Sumber metadata = SDF scan (Map model `loadSchemaPath`), deterministik dan tanpa
+// query DB (keputusan terkunci Pasca-Discovery). Berbeda dengan jalur restore R20
+// (`deriveSoftDeleteFkChecks`, introspeksi DB) yang TIDAK diubah di sini.
+
+/**
+ * Normalisasi nilai `onDelete` IR (camelCase) ke semantik FK-SD (keputusan terkunci Q5):
+ *   - 'cascade'                        -> 'cascade'
+ *   - 'setNull'                        -> 'setNull' (pass-through; ditolak validator Phase 05, bukan di sini)
+ *   - 'restrict' / 'noAction' / absent -> 'restrict' (default blok)
+ *
+ * Nilai di luar whitelist (`cascade`/`restrict`/`setNull`/`noAction`) sudah ditolak
+ * schema-validator (validateRelations), sehingga input ke fungsi ini dijamin salah satu
+ * dari empat itu atau absent (undefined/null). Fallback konservatif ke 'restrict' (blok).
+ *
+ * @param {string|undefined|null} onDelete - nilai onDelete dari IR relasi
+ * @returns {'cascade'|'restrict'|'setNull'}
+ */
+function normalizeFkOnDelete(onDelete) {
+  if (onDelete === 'cascade') return 'cascade';
+  if (onDelete === 'setNull') return 'setNull';
+  return 'restrict';
+}
+
+/**
+ * Muat Map model SDF secara graceful untuk SDF scan FK-SD-4. Berbeda dengan
+ * `resolveSoftDeleteForTable` (yang ERROR bila schema-path absen, R12), derivasi registry
+ * FK TIDAK boleh menggagalkan generate. Tiga kondisi -> kembalikan null (derivasi kosong):
+ *   - `--schema-path` absen/kosong            (tabel non-soft-delete tak wajib schema-path)
+ *   - `loadSchemaPath` gagal (folder/SDF invalid)
+ *   - mode single-file: tetap memuat 1 model, tetapi scan lintas-tabel natural kosong
+ *     (parent/anak tabel lain tidak ada di Map) -> field dihilangkan secara graceful.
+ *
+ * @param {string|null|undefined} schemaPath - nilai flag --schema-path
+ * @returns {Map<string, Object>|null} Map model SDF, atau null bila tak tersedia
+ */
+function loadSchemaMapGraceful(schemaPath) {
+  if (typeof schemaPath !== 'string' || schemaPath.trim() === '') return null;
+  try {
+    return loadSchemaPath(schemaPath);
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Resolusi IR model parent yang dirujuk sebuah relasi `belongsTo`. `rel.target` konvensinya
+ * adalah nama tabel target: `schema introspect` menamai relasi = nama tabel target, dan bila
+ * `target` eksplisit absen IR fallback ke nama relasi (`ir-builder.js:198`), sehingga relasi
+ * introspeksi tetap menunjuk tabel yang benar. `findModelByTable` menerima nama bare maupun
+ * qualified. Konservatif: target tak cocok model mana pun -> null; bare-name ambigu (>1
+ * schema, findModelByTable melempar) -> null.
+ *
+ * @param {Map<string, Object>} models - Map model SDF
+ * @param {Object} rel - relasi IR (harus belongsTo)
+ * @returns {Object|null} IR model parent, atau null
+ */
+function resolveBelongsToParent(models, rel) {
+  if (!rel || rel.type !== 'belongsTo') return null;
+  const target = rel.target;
+  if (typeof target !== 'string' || target === '') return null;
+  try {
+    return findModelByTable(models, target);
+  } catch (err) {
+    return null;
+  }
+}
+
+// Komparator determinisme snapshot (independen urutan deklarasi/urutan file loader).
+function compareFkParent(a, b) {
+  const ka = `${a.refTable}|${a.columns.join(',')}`;
+  const kb = `${b.refTable}|${b.columns.join(',')}`;
+  return ka < kb ? -1 : ka > kb ? 1 : 0;
+}
+function compareFkChild(a, b) {
+  const ka = `${a.childTable}|${a.childColumns.join(',')}`;
+  const kb = `${b.childTable}|${b.childColumns.join(',')}`;
+  return ka < kb ? -1 : ka > kb ? 1 : 0;
+}
+
+/**
+ * FK-SD-4 FORWARD registry (`softDeleteFkParents`). Untuk tabel `tableName`, daftar FK
+ * outbound (relasi `belongsTo`) yang parent-nya soft-delete-enabled (SDF `softDelete.enabled
+ * === true`). Dikonsumsi FK-SD-1 (forward block create/update anak ke parent terhapus).
+ *
+ * Berlaku untuk SEMUA tabel, TERMASUK tabel anak yang bukan soft-delete (mis. `visitors`):
+ * hanya FK ke parent soft-delete yang masuk. Shape per-entry sengaja subset
+ * `softDeleteFkChecks` (tanpa `parentSoftDelete`, karena di sini setiap entry pasti
+ * soft-delete) agar emit FK-SD-1 dapat memakai ulang pola SQL parent-aktif restore (R20):
+ *   { columns: [localKey], refTable: <qualified>, refColumns: [references] }
+ *
+ * `localKey`/`references` dijamin string tunggal oleh validator (validateRelations
+ * mewajibkan keduanya string), sehingga selalu single-column array. Graceful empty bila
+ * Map/IR/target tidak tersedia (single-file mode, schema-path absen).
+ *
+ * @param {Map<string, Object>|null} models - Map model SDF (null -> [])
+ * @param {string} tableName - nama tabel (bare atau schema.table)
+ * @returns {Array<{columns:string[], refTable:string, refColumns:string[]}>}
+ */
+function deriveSoftDeleteFkParents(models, tableName) {
+  if (!models) return [];
+  let ir;
+  try {
+    ir = findModelByTable(models, tableName);
+  } catch (err) {
+    return [];
+  }
+  if (!ir || !ir.relations) return [];
+
+  const parents = [];
+  for (const rel of Object.values(ir.relations)) {
+    if (!rel || rel.type !== 'belongsTo') continue;
+    if (typeof rel.localKey !== 'string' || typeof rel.references !== 'string') continue;
+    const parentModel = resolveBelongsToParent(models, rel);
+    if (!parentModel || !isSoftDeleteEnabled(parentModel)) continue;
+    parents.push({
+      columns: [rel.localKey],
+      refTable: parentModel.qualifiedName || parentModel.tableName,
+      refColumns: [rel.references]
+    });
+  }
+  parents.sort(compareFkParent);
+  return parents;
+}
+
+/**
+ * FK-SD-4 REVERSE registry (`softDeleteFkChildren`). Untuk tabel master `tableName`, pindai
+ * SELURUH model lain di Map: tiap relasi `belongsTo` yang target-nya = master ini berarti
+ * tabel pemilik relasi adalah anak. Rekam tabel anak, kolom FK lokal anak, `onDelete`
+ * (dinormalisasi Q5), dan status soft-delete anak. Dikonsumsi FK-SD-2 (restrict) & FK-SD-3
+ * (cascade).
+ *
+ * Hanya relasi `belongsTo` yang diperhitungkan: FK fisik selalu berada di tabel anak yang
+ * mendeklarasikannya sebagai `belongsTo` (introspeksi DB menghasilkan FK hanya pada child).
+ * `hasMany`/`hasOne` adalah view logis inverse dari FK yang sama (kolom-nya bukan FK fisik
+ * di tabel pendeklarasi), sehingga TIDAK dipakai agar tidak salah-arah/duplikat. Pencocokan
+ * master dilakukan dengan me-resolve target relasi ke model lalu membandingkan qualifiedName
+ * (robust terhadap target bare vs qualified). Self-reference (anak == master) sah dan
+ * disertakan. Pemanggil HARUS hanya memanggil ini untuk tabel soft-delete (guard
+ * hasSoftDeleteColumns); fungsi sendiri tidak menambah guard itu.
+ *
+ * `parentColumn` (= `rel.references`) membawa kolom MASTER yang dirujuk FK anak. FK-SD-2/3
+ * mem-query anak dengan `WHERE <childColumn> = <nilai parentColumn master row>`; mengandalkan
+ * PK master salah bila FK merujuk kolom non-PK. Diambil dari relasi, BUKAN diasumsikan = PK.
+ * Sejalan forward derivation, `localKey`/`references` wajib string tunggal (composite ditolak
+ * validator); entry tanpa keduanya string di-skip (defensif, konsisten determinisme snapshot).
+ *
+ * @param {Map<string, Object>|null} models - Map model SDF (null -> [])
+ * @param {string} tableName - nama tabel master (bare atau schema.table)
+ * @returns {Array<{childTable:string, childColumns:string[], parentColumn:string, onDelete:string, childSoftDelete:boolean}>}
+ */
+function deriveSoftDeleteFkChildren(models, tableName) {
+  if (!models) return [];
+  let masterIr;
+  try {
+    masterIr = findModelByTable(models, tableName);
+  } catch (err) {
+    return [];
+  }
+  if (!masterIr) return [];
+  const masterQualified = masterIr.qualifiedName || masterIr.tableName;
+
+  const children = [];
+  for (const childModel of models.values()) {
+    if (!childModel || !childModel.relations) continue;
+    for (const rel of Object.values(childModel.relations)) {
+      if (!rel || rel.type !== 'belongsTo') continue;
+      if (typeof rel.localKey !== 'string' || typeof rel.references !== 'string') continue;
+      const parentModel = resolveBelongsToParent(models, rel);
+      if (!parentModel) continue;
+      if ((parentModel.qualifiedName || parentModel.tableName) !== masterQualified) continue;
+      children.push({
+        childTable: childModel.qualifiedName || childModel.tableName,
+        childColumns: [rel.localKey],
+        parentColumn: rel.references,
+        onDelete: normalizeFkOnDelete(rel.onDelete),
+        childSoftDelete: isSoftDeleteEnabled(childModel)
+      });
+    }
+  }
+  children.sort(compareFkChild);
+  return children;
+}
+
+/**
+ * FK-SD-3 (Fase 1.5) — derivasi closure cascade transitif untuk master soft-delete.
+ * Mengadopsi algoritma spike Phase 04s (`buildCascadeClosure`, terbukti deterministik +
+ * cycle-safe) menjadi fungsi produksi. Dari `masterTable`, hitung peta node (master +
+ * SELURUH keturunan yang reachable lewat edge `onDelete:cascade` ke anak soft-delete),
+ * masing-masing membawa metadata yang dibutuhkan walk runtime (Phase 04b) untuk
+ * men-soft-delete dirinya + menjalar lebih dalam. Closure dipersist PENUH di RDF master
+ * (keputusan orchestrator) agar template Phase 04b tetap Map-free: tidak ada lookup
+ * lintas-RDF/akses DB saat codegen.
+ *
+ * Tiap node menyimpan:
+ *   - table     : nama qualified node
+ *   - pk        : primary key node (string bila single-column, array bila composite)
+ *                 dari IR `primaryKey`
+ *   - reusable  : [{field, length}] dari IR `softDelete.reusable` node ([] bila tidak ada)
+ *   - children  : SELURUH anak langsung (cascade + restrict + setNull), tiap entry
+ *                 { childTable, childColumn, parentColumn, onDelete, childSoftDelete }.
+ *                 Anak restrict/setNull DIREKAM (agar restrict-per-node Phase 04c bisa
+ *                 cek di SETIAP node, bukan hanya master) tetapi TIDAK memicu rekursi.
+ *
+ * Aturan expand (rekursi): HANYA ke `childTable` dari edge `onDelete==='cascade'` yang
+ * `childSoftDelete===true`. Edge cascade ke anak NON-soft-delete direkam di `children`
+ * (`childSoftDelete:false`) tetapi TIDAK di-expand dan TIDAK error di sini (konfigurasi
+ * itu ditolak validator Phase 05). Edge restrict/setNull direkam tetapi tidak di-expand.
+ *
+ * Cycle-safe (level closure): `visited` set berisi qualified table name; tabel yang sudah
+ * masuk `nodes` tidak di-expand ulang, sehingga closure pasti terminasi pada graf
+ * ber-cycle (self-reference, A→B→A) maupun diamond (anak dengan ≥2 parent cascade diproses
+ * sekali). `parentColumn = rel.references` (BUKAN diasumsikan PK), konsisten Phase 03.
+ *
+ * `order` = urutan kunjungan node DFS pre-order dengan anak cascade dikunjungi menurut
+ * urutan sorted `deriveSoftDeleteFkChildren` (master lebih dulu, lalu descendant). Stabil
+ * dan deterministik untuk snapshot RDF.
+ *
+ * Graceful: Map null/parsial (single-file, `--schema-path` absen) → `deriveSoftDeleteFkChildren`
+ * mengembalikan [] sehingga tree berisi hanya node master tanpa children, konsisten Phase 01.
+ * (Pemanggil men-guard persist dengan ≥1 anak cascade, sehingga kasus graceful itu tidak
+ * mempersist field sama sekali.)
+ *
+ * @param {Map<string, Object>|null} models - Map model SDF
+ * @param {string} masterTable - nama tabel master (bare atau schema.table)
+ * @returns {{ master:string, order:string[], nodes: Object<string, {table:string, pk:(string|string[]), reusable:Array<{field:string,length:number}>, children:Array<{childTable:string,childColumn:string,parentColumn:string,onDelete:string,childSoftDelete:boolean}>}> }}
+ */
+function buildSoftDeleteCascadeTree(models, masterTable) {
+  let masterIr = null;
+  if (models) {
+    try {
+      masterIr = findModelByTable(models, masterTable);
+    } catch (err) {
+      masterIr = null;
+    }
+  }
+  // Map tak tersedia / master tak ada di Map (single-file, schema-path absen): pakai nama
+  // tabel apa adanya. directChildren akan kosong (deriveSoftDeleteFkChildren graceful),
+  // menghasilkan tree minimal (hanya master, tanpa expand). Konsisten Phase 01.
+  const masterQ = masterIr
+    ? (masterIr.qualifiedName || masterIr.tableName)
+    : masterTable;
+
+  const nodes = {};
+  const order = [];
+  const visited = new Set();
+  const stack = [masterQ];
+
+  while (stack.length) {
+    const tableQ = stack.pop();
+    if (visited.has(tableQ)) continue;   // cycle/diamond guard: tabel sudah diproses
+    visited.add(tableQ);
+
+    const ir = models ? models.get(tableQ) : null;
+    const pkArr = (ir && Array.isArray(ir.primaryKey)) ? ir.primaryKey : [];
+    const reusable = (ir && ir.softDelete && Array.isArray(ir.softDelete.reusable))
+      ? ir.softDelete.reusable.map((r) => ({ field: r.field, length: r.length }))
+      : [];
+
+    // Anak langsung — derivasi REVERSE registry ASLI (Phase 01/03), sudah membawa
+    // childColumns/parentColumn/onDelete/childSoftDelete dan tersortir deterministik.
+    const directChildren = deriveSoftDeleteFkChildren(models, tableQ);
+
+    nodes[tableQ] = {
+      table: tableQ,
+      pk: pkArr.length === 1 ? pkArr[0] : pkArr.slice(),
+      reusable,
+      children: directChildren.map((c) => ({
+        childTable: c.childTable,
+        childColumn: c.childColumns[0],
+        parentColumn: c.parentColumn,
+        onDelete: c.onDelete,
+        childSoftDelete: c.childSoftDelete
+      }))
+    };
+    order.push(tableQ);
+
+    // Expand HANYA edge cascade ke anak soft-delete-enabled. Push REVERSE agar pop dalam
+    // urutan sorted (DFS pre-order stabil). Cascade→non-SD & restrict/setNull TIDAK di-expand.
+    const toExpand = [];
+    for (const c of directChildren) {
+      if (c.onDelete !== 'cascade' || !c.childSoftDelete) continue;
+      if (visited.has(c.childTable)) continue;
+      toExpand.push(c.childTable);
+    }
+    for (let i = toExpand.length - 1; i >= 0; i--) stack.push(toExpand[i]);
+  }
+
+  return { master: masterQ, order, nodes };
+}
+
 // ============================================================================
 // ADVISORIES (informational) — untuk payload validate
 // ============================================================================
@@ -1115,6 +1700,13 @@ class PayloadGenerator {
     console.log(`Table: ${payloadData.tableName}`);
     console.log(`Primary Key: ${payloadData.primaryKey}`);
 
+    // Flag kehadiran kolom soft-delete di DB (R12). DITANGKAP dari daftar kolom DB
+    // SEBELUM strip fieldName, supaya resolveSoftDeleteForTable/derivation (~1786)
+    // tetap jalan dan tetap ERROR bila kolom hadir di DB tetapi SDF tidak punya blok
+    // softDelete valid. Strip middle-ground beroperasi pada PROYEKSI fieldName, bukan
+    // pada daftar kolom DB yang dipakai cek konsistensi.
+    let hasSoftDeleteColumns = false;
+
     // Get fields from database
     if (this.db.pool) {
       const columns = await this.db.getColumns(args.table);
@@ -1130,6 +1722,22 @@ class PayloadGenerator {
           payloadData.auditColumns = false;
           console.log('No audit columns detected in table: setting auditColumns: false');
         }
+
+        // Soft-delete middle-ground (audit-parity): keluarkan tiga kolom soft-delete
+        // (is_deleted/deleted_at/deleted_by) dari PROYEKSI fieldName agar RDF bersih.
+        // Seluruh turunan (datatablesQuery SQL, datatablesWhere, dateTimeFields,
+        // fieldValidation) diturunkan dari fieldName SETELAH titik ini sehingga ikut
+        // bersih otomatis. validFields MODEL tetap memuat tiga kolom (di-append di
+        // template) supaya mekanisme visibility R15 tetap lolos guard BaseModel.
+        // Flag ditangkap dari kolom DB (bukan fieldName yang sudah di-strip).
+        hasSoftDeleteColumns = SOFT_DELETE_COLUMNS.some(col => columns.includes(col));
+        if (hasSoftDeleteColumns) {
+          const softDeleteStripped = payloadData.fieldName.filter(col => SOFT_DELETE_COLUMNS.includes(col));
+          payloadData.fieldName = payloadData.fieldName.filter(col => !SOFT_DELETE_COLUMNS.includes(col));
+          if (softDeleteStripped.length > 0) {
+            console.log(`Soft-delete columns excluded from RDF fieldName: ${softDeleteStripped.join(', ')}`);
+          }
+        }
       }
     }
 
@@ -1222,6 +1830,78 @@ class PayloadGenerator {
         .map((c) => ({ name: c.name, fields: c.columns }));
     }
 
+    // Soft-delete derivation (R12/R13): bila tabel memiliki satu atau lebih kolom
+    // soft-delete (is_deleted/deleted_at/deleted_by), wajib resolusi SDF dengan blok
+    // softDelete valid lalu turunkan blok ke RDF (+ override maxLength reusable = base).
+    // Guard ketat: tabel non-soft-delete tidak menyentuh jalur ini sama sekali, sehingga
+    // output byte-identik baseline (--schema-path diabaikan untuk tabel non-soft-delete).
+    // CATATAN: `hasSoftDeleteColumns` di-capture dari daftar kolom DB SEBELUM strip
+    // fieldName (lihat ~1662), karena fieldName kini sudah tidak memuat tiga kolom.
+
+    // FK-SD-4 (Fase 1.5): muat Map SDF SEKALI secara graceful untuk derivasi registry FK
+    // (forward `softDeleteFkParents` + reverse `softDeleteFkChildren`). Berbeda dengan
+    // resolveSoftDeleteForTable yang ERROR bila schema-path absen (R12), registry FK tidak
+    // boleh menggagalkan generate: Map null -> derivasi kosong (field dihilangkan secara
+    // graceful). Tidak menambah query DB saat runtime (derivasi hanya saat generate).
+    const fkRegistryModels = loadSchemaMapGraceful(args['schema-path']);
+
+    if (hasSoftDeleteColumns) {
+      const sdfSoftDelete = resolveSoftDeleteForTable(payloadData.tableName, args['schema-path']);
+      applySoftDeleteDerivation(payloadData, sdfSoftDelete);
+      const reusableCount = Array.isArray(sdfSoftDelete.reusable)
+        ? sdfSoftDelete.reusable.length
+        : 0;
+
+      // FK-awareness (R20): derive daftar cek FK + status parent-soft-delete dari introspeksi
+      // DB. Top-level (pola uniqueConstraints), guarded oleh hasSoftDeleteColumns → tabel
+      // non-soft-delete tidak menyentuh field ini (diff-zero baseline terjaga). Dikonsumsi
+      // template restore (R20) saat action.restore aktif. TIDAK diubah Fase 1.5.
+      payloadData.softDeleteFkChecks = await deriveSoftDeleteFkChecks(this.db, payloadData.tableName);
+      const softDeleteParentCount = payloadData.softDeleteFkChecks.filter((c) => c.parentSoftDelete).length;
+
+      // FK-SD-4 REVERSE registry (Fase 1.5): anak yang menunjuk master ini, untuk FK-SD-2
+      // (restrict) & FK-SD-3 (cascade). Persist SELALU untuk tabel soft-delete (boleh []),
+      // mengikuti preseden softDeleteFkChecks. Diturunkan via SDF scan (Map), bukan DB.
+      payloadData.softDeleteFkChildren = deriveSoftDeleteFkChildren(fkRegistryModels, payloadData.tableName);
+
+      // FK-SD-3 (Fase 1.5, Phase 04a/04b): closure cascade transitif (master + seluruh keturunan
+      // reachable lewat edge cascade ke anak soft-delete). Persist PENUH di RDF master agar
+      // walk Phase 04b Map-free. Guard: HANYA bila master punya ≥1 anak langsung
+      // onDelete:cascade YANG anaknya soft-delete-enabled (childSoftDelete === true) — sebab
+      // softDeleteCascadeTree hanya bermakna bila ada cascade NYATA yang bisa di-walk. Edge
+      // cascade→non-soft-delete adalah config invalid (ditolak validator Phase 05) → tidak
+      // mempersist tree degenerate. Master tanpa cascade expandable → field DIHILANGKAN
+      // (diff-zero baseline + komposisi Phase 03 restrict-only tetap utuh). Penempatan tepat
+      // setelah softDeleteFkChildren → urutan key RDF deterministik.
+      const hasCascadeChild = payloadData.softDeleteFkChildren.some(
+        (c) => c.onDelete === 'cascade' && c.childSoftDelete === true
+      );
+      let cascadeNodeCount = 0;
+      if (hasCascadeChild) {
+        payloadData.softDeleteCascadeTree =
+          buildSoftDeleteCascadeTree(fkRegistryModels, payloadData.tableName);
+        cascadeNodeCount = payloadData.softDeleteCascadeTree.order.length;
+      }
+
+      console.log(
+        `Soft-delete detected: derived softDelete block from SDF ` +
+        `('${args['schema-path']}', ${reusableCount} reusable field(s); ` +
+        `${payloadData.softDeleteFkChecks.length} FK check(s), ${softDeleteParentCount} soft-delete parent(s); ` +
+        `${payloadData.softDeleteFkChildren.length} reverse child(ren)` +
+        (hasCascadeChild ? `; cascade closure ${cascadeNodeCount} node(s)` : '') + `).`
+      );
+    }
+
+    // FK-SD-4 FORWARD registry (Fase 1.5): FK outbound tabel ini ke parent soft-delete, untuk
+    // FK-SD-1 (forward block create/update). Berlaku untuk SEMUA tabel TERMASUK anak
+    // non-soft-delete (mis. visitors), sehingga jalur ini di LUAR guard hasSoftDeleteColumns.
+    // Persist HANYA bila array non-kosong → tabel netral (tanpa softDelete & tanpa FK ke
+    // tabel soft-delete) tetap byte-identik baseline (diff-zero terjaga).
+    const softDeleteFkParents = deriveSoftDeleteFkParents(fkRegistryModels, payloadData.tableName);
+    if (softDeleteFkParents.length > 0) {
+      payloadData.softDeleteFkParents = softDeleteFkParents;
+    }
+
     // Save payload
     this.ensureOutputDir();
     const filename = baseFilename + '.json';
@@ -1239,6 +1919,15 @@ class PayloadGenerator {
     console.log();
     console.log(`Payload saved: ${outputPath}`);
     console.log(`Query saved:   ${sqlOutputPath}`);
+
+    // Checkpoint 2 soft-delete dashboard guard (WARNING, non-blocking): bila RDF yang baru
+    // ditulis adalah tabel soft-delete, scan dashboard yang sudah ada di outputDir terhadap
+    // registry soft-delete saat ini lalu peringatkan dashboard yang bocor. Gating
+    // isSoftDeleteEnabled memastikan tabel netral tidak memicu scan (no noise, no regresi).
+    // Tidak boleh menggagalkan generate (fungsi warn bersifat best-effort, tidak throw).
+    if (isSoftDeleteEnabled(payloadData)) {
+      warnSoftDeleteDashboardDrift(this.outputDir);
+    }
   }
 }
 
@@ -1863,6 +2552,14 @@ class SchemaValidator {
     enrichedColumns = tempGenerator.enrichDetailedColumnsWithBoolean(enrichedColumns, booleanColumns);
     const stringColumns = collectStringColumns(enrichedColumns);
 
+    // Soft-delete middle-ground (audit-parity): bila blok softDelete dipertahankan di
+    // RDF (lewat spread ...oldPayload), keluarkan tiga kolom soft-delete dari fieldName
+    // hasil sync sama seperti jalur generate. Gate dari oldPayload (blok softDelete tidak
+    // berubah saat sync). Tabel non-soft-delete: gate false → newFieldName byte-identik
+    // baseline. Strip di KEDUA loop agar RDF lama (yang masih memuat tiga kolom di
+    // fieldName) ikut dibersihkan secara idempoten saat sync.
+    const stripSoftDelete = isSoftDeleteEnabled(oldPayload);
+
     // Bangun fieldName baru: pertahankan urutan field lama, tambahkan field baru di akhir.
     // Kolom yang sebelumnya dicantumkan user di payload (termasuk kolom audit default)
     // dipertahankan. Kolom audit default yang tidak pernah ada di payload tidak
@@ -1870,6 +2567,7 @@ class SchemaValidator {
     const newFieldName = [];
     // Pertahankan field lama yang masih ada di database
     for (const field of oldPayload.fieldName) {
+      if (stripSoftDelete && SOFT_DELETE_COLUMNS.includes(field)) continue;
       if (dbColumns.includes(field)) {
         newFieldName.push(field);
       }
@@ -1878,6 +2576,7 @@ class SchemaValidator {
     for (const col of dbColumns) {
       if (newFieldName.includes(col)) continue;
       if (DEFAULT_AUDIT_COLUMNS.includes(col)) continue;
+      if (stripSoftDelete && SOFT_DELETE_COLUMNS.includes(col)) continue;
       newFieldName.push(col);
     }
 
@@ -2056,5 +2755,16 @@ module.exports = {
   collectStringColumns,
   isDefaultSearchableColumn,
   applyIsActiveDefaultScope,
-  buildPayloadAdvisories
+  applySoftDeleteDerivation,
+  resolveSoftDeleteForTable,
+  deriveSoftDeleteFkChecks,
+  isParentSoftDelete,
+  findModelByTable,
+  loadSchemaMapGraceful,
+  normalizeFkOnDelete,
+  deriveSoftDeleteFkParents,
+  deriveSoftDeleteFkChildren,
+  buildSoftDeleteCascadeTree,
+  buildPayloadAdvisories,
+  warnSoftDeleteDashboardDrift
 };