@restforgejs/platform 5.1.4 → 5.1.6

package/generators/lib/data/data-scope.js

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * data-scope — Helper bersama untuk scope flags & derivasi path file data.
+ *
+ * Dipakai oleh `data pull` dan `data push` agar kedua command berbagi satu-satunya
+ * sumber kebenaran untuk: (a) parsing `--schema` comma-separated, (b) validasi
+ * "tepat satu" dari `{--table, --schema, --all-schemas}`, (c) derivasi path file
+ * relatif (bersarang per schema vs flat), dan (d) resolusi scope flag → daftar IR.
+ *
+ * Model scope (mirror `schema introspect`, namun "tepat satu" alih-alih kombinasi):
+ *   --table=<name>        → satu IR via findTableOrThrow (qualified/unqualified).
+ *   --schema=<LIST>       → semua IR ber-schemaName ∈ LIST; 0 match = exit 2 (anti-typo).
+ *   --all-schemas         → seluruh IR (boleh kosong → caller tangani sebagai 0 tabel).
+ *
+ * Aturan path seragam (Q2): layout ditentukan MURNI oleh schema tabel di IR.
+ *   ber-schema  → `<schemaName>/<tableName>.json`
+ *   tanpa schema → `<tableName>.json` (flat root)
+ *
+ * Murni in-memory, tanpa I/O maupun koneksi DB.
+ *
+ * @module generators/lib/data/data-scope
+ */
+
+const path = require('path');
+const { findTableOrThrow, getNamespace } = require('./sdf-reader');
+
+/**
+ * Buat Error dengan exitCode terlampir (precondition/usage = 2).
+ * @param {string} message
+ * @param {number} exitCode
+ * @returns {Error}
+ */
+function failWith(message, exitCode) {
+    const err = new Error(message);
+    err.exitCode = exitCode;
+    return err;
+}
+
+/**
+ * Parse flag `--schema` (single atau comma-separated) → array nama schema.
+ *
+ * Selaras pola `schema introspect` (introspect.js:175-180): split koma, trim tiap
+ * elemen, buang elemen kosong. Mengembalikan `null` bila bukan string atau hasil
+ * akhir kosong (mis. `--schema=` atau `--schema=,,`), sehingga caller dapat
+ * memperlakukan "schema tidak disebut" secara seragam.
+ *
+ * @param {*} value - Nilai flag --schema
+ * @returns {string[]|null}
+ */
+function parseSchemaFlag(value) {
+    if (typeof value !== 'string') return null;
+    const parts = value.split(',').map((s) => s.trim()).filter(Boolean);
+    if (parts.length === 0) return null;
+    return parts;
+}
+
+/**
+ * Path file data relatif terhadap storage dir, diturunkan MURNI dari schema IR.
+ *
+ * Satu-satunya titik derivasi nama file untuk pull & push (menghindari drift tiga
+ * titik edit lama). Tabel ber-schema → bersarang `<schemaName>/<tableName>.json`;
+ * tabel tanpa schema → flat `<tableName>.json`. Pemanggil cukup
+ * `path.join(storageDir, relDataFilePath(ir))`.
+ *
+ * @param {Object} ir - IR model SDF satu tabel
+ * @returns {string} Path relatif (memakai separator OS via path.join)
+ */
+function relDataFilePath(ir) {
+    const { schemaName } = getNamespace(ir);
+    return schemaName
+        ? path.join(schemaName, `${ir.tableName}.json`)
+        : `${ir.tableName}.json`;
+}
+
+/**
+ * Tegakkan "tepat satu" dari `{--table, --schema, --all-schemas}`.
+ *
+ * Arg-parser tidak punya mekanisme XOR lintas-flag (hanya `required` per-flag),
+ * sehingga validasi tiga-arah ditegakkan di sini. Dipanggil SEBELUM load SDF /
+ * koneksi DB. Keduanya/lebih maupun tidak ada satupun → exit 2 dengan pesan sama.
+ *
+ * @param {Object} args - argumen ter-parse (args.table, args['all-schemas'])
+ * @param {string[]|null} schemaList - hasil parseSchemaFlag(args.schema)
+ * @throws {Error} exitCode=2 bila BUKAN tepat satu yang aktif
+ */
+function validateScopeFlags(args, schemaList) {
+    const hasTable = args.table != null && args.table !== '';
+    const hasSchema = Array.isArray(schemaList) && schemaList.length > 0;
+    const hasAll = args['all-schemas'] === true;
+
+    const count = (hasTable ? 1 : 0) + (hasSchema ? 1 : 0) + (hasAll ? 1 : 0);
+    if (count !== 1) {
+        throw failWith('Specify exactly one of --table, --schema, or --all-schemas.', 2);
+    }
+}
+
+/**
+ * Resolusi scope flag → daftar IR yang akan diproses (urutan deklarasi Map).
+ *
+ * Mengasumsikan validateScopeFlags() sudah lolos (tepat satu flag aktif).
+ *   --table        → [findTableOrThrow(models, args.table)] (exit 2 bila tak terdaftar/ambigu).
+ *   --schema=<L>   → subset IR ber-schemaName ∈ L; 0 match → exit 2 (sinyal typo).
+ *   --all-schemas  → seluruh IR (boleh kosong → caller perlakukan sebagai 0 tabel, exit 0).
+ *
+ * @param {Map<string, Object>} models - hasil loadSdf
+ * @param {Object} args - argumen ter-parse
+ * @param {string[]|null} schemaList - hasil parseSchemaFlag(args.schema)
+ * @returns {Object[]} array IR sesuai scope
+ * @throws {Error} exitCode=2 (table tak terdaftar/ambigu, atau --schema 0-match)
+ */
+function resolveScope(models, args, schemaList) {
+    const hasTable = args.table != null && args.table !== '';
+    if (hasTable) {
+        return [findTableOrThrow(models, args.table)];
+    }
+
+    if (Array.isArray(schemaList) && schemaList.length > 0) {
+        const set = new Set(schemaList);
+        const subset = [...models.values()].filter((ir) => set.has(getNamespace(ir).schemaName));
+        if (subset.length === 0) {
+            throw failWith(`No tables found for schema(s): ${schemaList.join(', ')}.`, 2);
+        }
+        return subset;
+    }
+
+    // --all-schemas: seluruh tabel (semua schema, termasuk schemaless). Boleh kosong.
+    return [...models.values()];
+}
+
+module.exports = {
+    parseSchemaFlag,
+    relDataFilePath,
+    validateScopeFlags,
+    resolveScope,
+    // Diekspor untuk reuse/test internal.
+    _internal: { failWith }
+};

package/generators/lib/data/envelope.js

@@ -4,27 +4,33 @@
  * envelope — Bentuk + I/O envelope file data.
  *
  * Struktur envelope (urutan key wajib dipertahankan):
- *   { format_version, table, source_dialect, columns, rows }
+ *   { format_version, schema, table, source_dialect, columns, rows }
+ *
+ * `schema` (= `ir.schemaName`, `null` bila tanpa schema) ditambahkan di format
+ * version 1.1. File 1.0 (tanpa `schema`) tetap diterima oleh `validateEnvelope`
+ * untuk back-compat baca `data push`.
  *
  * Mengacu pada docs/plan/data-pull-push/data-pull-push-03-data-format.md.
  *
  * @module generators/lib/data/envelope
  */
 
-const FORMAT_VERSION = '1.0';
+const FORMAT_VERSION = '1.1';
 
 /**
  * Bangun header envelope (tanpa rows).
  *
  * @param {Object} args
+ * @param {string|null} [args.schema] - Nama schema (= ir.schemaName; null bila tanpa schema)
  * @param {string} args.table - Nama tabel
  * @param {string} args.sourceDialect - Dialect sumber (mis. 'postgresql')
  * @param {Array<Object>} args.columns - Daftar kolom { name, type, nullable, primary_key }
- * @returns {{format_version: string, table: string, source_dialect: string, columns: Array}}
+ * @returns {{format_version: string, schema: (string|null), table: string, source_dialect: string, columns: Array}}
  */
-function buildHeader({ table, sourceDialect, columns }) {
+function buildHeader({ schema = null, table, sourceDialect, columns }) {
   return {
     format_version: FORMAT_VERSION,
+    schema,
     table,
     source_dialect: sourceDialect,
     columns
@@ -58,11 +64,11 @@ function resolveSink(sink) {
  * Menulis header, meng-append rows per batch, lalu menutup array `rows` dan envelope.
  * Cocok untuk tabel besar karena rows tidak perlu ditahan seluruhnya di memori.
  * Output akhir adalah JSON valid dengan urutan key:
- *   format_version, table, source_dialect, columns, rows
+ *   format_version, schema, table, source_dialect, columns, rows
  *
  * Penggunaan:
  *   const w = new EnvelopeWriter(fs.createWriteStream(path));
- *   w.writeHeader({ table, sourceDialect, columns });
+ *   w.writeHeader({ schema, table, sourceDialect, columns });
  *   w.appendRows(batch1);
  *   w.appendRows(batch2);
  *   w.end();
@@ -83,16 +89,17 @@ class EnvelopeWriter {
 
   /**
    * Tulis prefix header dan buka array `rows`.
-   * @param {Object} header - { table, sourceDialect, columns }
+   * @param {Object} header - { schema, table, sourceDialect, columns }
    * @returns {EnvelopeWriter} this
    */
-  writeHeader({ table, sourceDialect, columns }) {
+  writeHeader({ schema, table, sourceDialect, columns }) {
     if (this._state !== 'init') {
       throw new Error('EnvelopeWriter: writeHeader() hanya boleh dipanggil sekali di awal');
     }
     const prefix =
       '{' +
       `"format_version":${JSON.stringify(FORMAT_VERSION)},` +
+      `"schema":${JSON.stringify(schema ?? null)},` +
       `"table":${JSON.stringify(table)},` +
       `"source_dialect":${JSON.stringify(sourceDialect)},` +
       `"columns":${JSON.stringify(columns)},` +
@@ -163,7 +170,11 @@ function parseEnvelope(jsonString) {
  * Validasi shape envelope. Throw (exitCode=1) bila tidak valid.
  *
  * Wajib: format_version (ada), table (string), columns (array of {name,type}),
- * rows (array of object).
+ * rows (array of object). Opsional: `schema` (string atau null bila ada).
+ *
+ * `format_version` tetap LENIENT (cukup ada/non-null) agar file 1.0 maupun 1.1
+ * sama-sama diterima tanpa penolakan versi. `schema` opsional untuk back-compat:
+ * file 1.0 (tanpa key `schema`) diterima; bila ada, wajib string atau null.
  *
  * @param {Object} obj
  * @returns {Object} obj yang sama (untuk chaining)
@@ -182,6 +193,11 @@ function validateEnvelope(obj) {
   if (obj.format_version === undefined || obj.format_version === null) {
     fail('field "format_version" wajib ada');
   }
+  // `schema` opsional (back-compat 1.0). Bila absen → diterima; bila ada → wajib
+  // string atau null. `null` eksplisit (1.1 tabel schemaless) tetap valid.
+  if (obj.schema !== undefined && obj.schema !== null && typeof obj.schema !== 'string') {
+    fail('field "schema" wajib berupa string atau null bila ada');
+  }
   if (typeof obj.table !== 'string' || obj.table === '') {
     fail('field "table" wajib berupa string non-kosong');
   }

package/generators/lib/data/pull-runner.js

@@ -3,17 +3,18 @@
 /**
  * pull-runner — Business logic command `data pull`.
  *
- * `run()` adalah dispatcher (single vs all-tables); `runOne(ir, ctx)` mengeksekusi
+ * `run()` adalah dispatcher (single vs multi-schema); `runOne(ir, ctx)` mengeksekusi
  * pull satu tabel dan mengelola executor-nya sendiri (Phase 02, data-pull-push-v2).
  *
  * Alur dispatcher `run()`:
  *   1. Resolve config DB (config-resolver) → loadConfig (dbschema-kit/connection); SEKALI.
- *   2. Validasi mutual-exclusive (sebelum load SDF / koneksi DB): tepat satu dari
- *      --table / --all-tables (keduanya / tidak keduanya → exit 2).
+ *   2. parseSchemaFlag + validateScopeFlags (sebelum load SDF / koneksi DB): tepat satu
+ *      dari --table / --schema / --all-schemas (selain itu → exit 2).
  *   3. Validasi --format (hanya 'json').
  *   4. Load SDF SEKALI → Map<qualifiedName, IR> (sdf-reader).
- *   5a. Jalur --table:      findTableOrThrow → runOne(ir, ctx) → ringkasan single.
- *   5b. Jalur --all-tables: iterasi models.values() FAIL-FAST (Q3) → runOne per IR →
+ *   5. resolveScope(models, args, schemaList) → daftar IR sesuai flag scope.
+ *   5a. Jalur --table:               satu IR → runOne(ir, ctx) → ringkasan single.
+ *   5b. Jalur --schema/--all-schemas: iterasi subset FAIL-FAST (Q3) → runOne per IR →
  *       ringkasan agregat. Tabel yang sudah selesai sebelum error tetap tertulis.
  *
  * Alur `runOne(ir, ctx)` (per tabel; metadata kolom/namespace/PK murni dari SDF IR):
@@ -37,11 +38,11 @@ const { resolveConfig, printDefaultConfigWarning } = require('../utils/config-re
 const { loadConfig } = require('../dbschema-kit/connection');
 const {
     loadSdf,
-    findTableOrThrow,
     irToColumns,
     getNamespace,
     getPrimaryKey
 } = require('./sdf-reader');
+const { parseSchemaFlag, validateScopeFlags, resolveScope, relDataFilePath } = require('./data-scope');
 const { createDialect, validateIdentifier } = require('./dialect-kit');
 const { createExecutor } = require('./db-executor');
 const { encodeValue } = require('./value-codec');
@@ -176,10 +177,12 @@ async function pullInBatches({ executor, dialect, queryTable, columns, pk, batch
 }
 
 /**
- * Pull satu tabel SDF ke file envelope JSON `<output>/<qualifiedName>.json`.
+ * Pull satu tabel SDF ke file envelope JSON (path via relDataFilePath: bersarang
+ * `<output>/<schema>/<table>.json` bila ber-schema, flat `<output>/<table>.json`
+ * bila tanpa schema).
  *
  * Mengelola executor-nya sendiri (buat → disconnect, termasuk cleanup file partial
- * saat error) agar isolasi per-tabel jelas dan jalur --all-tables dapat memanggilnya
+ * saat error) agar isolasi per-tabel jelas dan jalur multi-schema dapat memanggilnya
  * berulang tanpa kebocoran koneksi. Metadata kolom, namespace, dan PK murni dari IR.
  *
  * @param {Object} ir - IR model SDF satu tabel
@@ -188,24 +191,24 @@ async function pullInBatches({ executor, dialect, queryTable, columns, pk, batch
  * @param {string} ctx.sourceDialect - dialect kanonik untuk header envelope
  * @param {Object} ctx.args - argumen ter-parse (storage-path, force, limit, batch-size)
  * @param {string} ctx.cwd - working directory
- * @returns {Promise<{table: string, rows: number, file: string, source_dialect: string}>}
+ * @returns {Promise<{schema: (string|null), table: string, rows: number, file: string, source_dialect: string}>}
  */
 async function runOne(ir, ctx) {
     const { config, sourceDialect, args, cwd } = ctx;
 
     const columns = irToColumns(ir);
-    const { qualifiedName } = getNamespace(ir);
+    const { schemaName, qualifiedName } = getNamespace(ir);
     const rawPk = getPrimaryKey(ir);
     const pk = Array.isArray(rawPk) ? rawPk : [];
 
     // ── a. Cek file output (SEBELUM menulis/konek) ───────────────────────────────
-    // Nama file = qualifiedName SDF (bukan ir.tableName), agar dua tabel bernama sama
-    // di schema berbeda tidak collision (mis. `sales.order_item.json`). Tabel tanpa
-    // schema: qualifiedName === tableName → `visitors.json` (tak berubah). Titik pada
-    // qualifiedName dipertahankan (valid sebagai nama file). push (Phase 03) menurunkan
-    // nama file dengan aturan identik dari SDF.
+    // Path diturunkan dari relDataFilePath (aturan seragam Q2): tabel ber-schema →
+    // bersarang `<schema>/<table>.json` (mis. `sales/order_item.json`); tabel tanpa
+    // schema → flat `<table>.json` (mis. `visitors.json`). Helper bersama dengan push
+    // (data-scope) agar derivasi tidak drift. queryTable SELECT tetap memakai
+    // qualifiedName (identitas DB).
     const outputDir = path.resolve(cwd, args['storage-path']);
-    const outFile = path.join(outputDir, `${qualifiedName}.json`);
+    const outFile = path.join(outputDir, relDataFilePath(ir));
     if (fs.existsSync(outFile) && args.force !== true) {
         const rel = path.relative(cwd, outFile).split(path.sep).join('/');
         throw failWith(
@@ -238,11 +241,14 @@ async function runOne(ir, ctx) {
     let rowCount = 0;
     let fd = null;
     try {
-        fs.mkdirSync(outputDir, { recursive: true });
+        // Buat direktori parent dari outFile (bukan sekadar outputDir): pada layout
+        // bersarang, outFile berada di subfolder schema (mis. `<storage>/main/`) yang
+        // belum tentu ada. path.dirname mencakup subfolder schema maupun flat root.
+        fs.mkdirSync(path.dirname(outFile), { recursive: true });
         fd = fs.openSync(outFile, 'w');
 
         const writer = new EnvelopeWriter((chunk) => fs.writeSync(fd, chunk));
-        writer.writeHeader({ table: ir.tableName, sourceDialect, columns });
+        writer.writeHeader({ schema: schemaName, table: ir.tableName, sourceDialect, columns });
 
         rowCount = await pullInBatches({
             executor,
@@ -277,6 +283,7 @@ async function runOne(ir, ctx) {
     // ── e. Ringkasan per-tabel (tanpa `command`; dirakit caller) ─────────────────
     const relFile = path.relative(cwd, outFile).split(path.sep).join('/');
     return {
+        schema: schemaName,
         table: ir.tableName,
         rows: rowCount,
         file: relFile,
@@ -285,10 +292,10 @@ async function runOne(ir, ctx) {
 }
 
 /**
- * Jalankan command `data pull` (dispatcher: single-table vs --all-tables).
+ * Jalankan command `data pull` (dispatcher: single-table vs multi-schema).
  * @param {Object} args - argumen ter-parse dari contract
- * @returns {Promise<Object>} ringkasan single { command, table, rows, file, source_dialect }
- *   atau agregat { command, all_tables, table_count, total_rows, tables: [...] }
+ * @returns {Promise<Object>} ringkasan single { command, schema, table, rows, file, source_dialect }
+ *   atau agregat { command, scope, table_count, total_rows, tables: [...] }
  */
 async function run(args) {
     const cwd = process.cwd();
@@ -312,17 +319,12 @@ async function run(args) {
         throw failWith(e.message, 2);
     }
 
-    // ── 2. Validasi mutual-exclusive --table / --all-tables (SEBELUM SDF/DB) ──────
-    // Arg-parser tidak punya mekanisme XOR lintas-flag (hanya `required` per-flag),
-    // sehingga "tepat satu" ditegakkan di sini. Exit 2 (precondition/usage).
+    // ── 2. Validasi scope flags (SEBELUM SDF/DB) ─────────────────────────────────
+    // Tepat satu dari --table / --schema / --all-schemas (selain itu → exit 2).
+    // Helper bersama dengan push (data-scope) agar perilaku identik.
+    const schemaList = parseSchemaFlag(args.schema);
+    validateScopeFlags(args, schemaList);
     const hasTable = args.table != null && args.table !== '';
-    const hasAll = args['all-tables'] === true;
-    if (hasTable && hasAll) {
-        throw failWith('Specify exactly one of --table or --all-tables.', 2);
-    }
-    if (!hasTable && !hasAll) {
-        throw failWith('Specify either --table=<name> or --all-tables.', 2);
-    }
 
     // ── 3. Validasi --format ─────────────────────────────────────────────────────
     if (args.format !== 'json') {
@@ -350,10 +352,14 @@ async function run(args) {
         cwd
     };
 
+    // ── 5. Resolusi scope → daftar IR ────────────────────────────────────────────
+    // --table → [ir] (exit 2 bila tak terdaftar/ambigu); --schema → subset (exit 2
+    // bila 0-match); --all-schemas → seluruh IR (boleh kosong → agregat 0 tabel).
+    const subset = resolveScope(models, args, schemaList);
+
     // ── 5a. Jalur --table (single; regresi nol) ──────────────────────────────────
     if (hasTable) {
-        const ir = findTableOrThrow(models, args.table); // throw exitCode=2 bila tak terdaftar
-        const per = await runOne(ir, ctx);
+        const per = await runOne(subset[0], ctx);
         const summary = { command: 'pull', ...per };
 
         if (args.json === true) {
@@ -366,13 +372,14 @@ async function run(args) {
         return summary;
     }
 
-    // ── 5b. Jalur --all-tables (fail-fast Q3; agregat) ───────────────────────────
+    // ── 5b. Jalur --schema/--all-schemas (fail-fast Q3; agregat) ─────────────────
     // Iterasi mengikuti urutan insertion Map (file SDF ter-sort alfabetis). Error
     // pada satu tabel menghentikan loop (fail-fast); tabel yang sudah selesai
-    // sebelum error tetap tertulis (konsekuensi Q3/R4, didokumentasikan Phase 05).
+    // sebelum error tetap tertulis (konsekuensi Q3/R4, didokumentasikan Phase 03).
+    const scope = schemaList ? 'schema' : 'all-schemas';
     const tables = [];
     let totalRows = 0;
-    for (const ir of models.values()) {
+    for (const ir of subset) {
         const per = await runOne(ir, ctx);
         tables.push(per);
         totalRows += per.rows;
@@ -385,7 +392,7 @@ async function run(args) {
 
     const aggregate = {
         command: 'pull',
-        all_tables: true,
+        scope,
         table_count: tables.length,
         total_rows: totalRows,
         tables

package/generators/lib/data/push-runner.js

@@ -7,21 +7,23 @@
  * di-descope dari v1 (User konfirmasi 2026-06-03), sehingga flag `--mode`/`--force`
  * dihapus dari contract dan runner tidak lagi membaca/memvalidasi keduanya.
  *
- * `run()` adalah dispatcher (single vs all-tables); `runOne(ir, ctx)` mengeksekusi
+ * `run()` adalah dispatcher (single vs multi-schema); `runOne(ir, ctx)` mengeksekusi
  * push satu tabel dan mengelola executor-nya sendiri (Phase 03, data-pull-push-v2).
  *
  * Alur dispatcher `run()`:
  *   1. Resolve config DB tujuan (config-resolver) → loadConfig (dbschema-kit/connection); SEKALI.
- *   2. Validasi mutual-exclusive (sebelum load SDF / koneksi DB): tepat satu dari
- *      --table / --all-tables (keduanya / tidak keduanya → exit 2).
+ *   2. parseSchemaFlag + validateScopeFlags (sebelum load SDF / koneksi DB): tepat satu
+ *      dari --table / --schema / --all-schemas (selain itu → exit 2).
  *   3. Load SDF SEKALI → Map<qualifiedName, IR> (sdf-reader).
- *   4a. Jalur --table:      findTableOrThrow → runOne(ir, ctx) → ringkasan single (regresi nol).
- *   4b. Jalur --all-tables: topoSortByFk(models) → urutan parent→child (table-order); siklus →
- *       warning stderr + fallback urutan deklarasi. Loop FAIL-FAST (Q3); tabel tanpa file
- *       input di-SKIP (warning stderr, catat di skipped[], lanjut) → runOne per IR → agregat.
+ *   4. resolveScope(models, args, schemaList) → daftar IR sesuai flag scope.
+ *   4a. Jalur --table:               satu IR → runOne(ir, ctx) → ringkasan single (regresi nol).
+ *   4b. Jalur --schema/--all-schemas: topoSortByFk(SUBSET) → urutan parent→child (table-order);
+ *       siklus → warning stderr + fallback urutan deklarasi. Loop FAIL-FAST (Q3); tabel tanpa
+ *       file input di-SKIP (warning stderr, catat di skipped[], lanjut) → runOne per IR → agregat.
  *
  * Alur `runOne(ir, ctx)` (per tabel; metadata kolom/namespace/PK murni dari SDF IR):
- *   a. Derive nama file dari SDF (aturan IDENTIK pull): {cwd}/{input}/{qualifiedName}.json.
+ *   a. Derive nama file dari SDF (aturan IDENTIK pull, relDataFilePath): bersarang
+ *      `<input>/<schema>/<table>.json` bila ber-schema, flat `<input>/<table>.json`.
  *      File tidak ada → exit 1. Baca + parseEnvelope + validateEnvelope (shape invalid → exit 1).
  *   b. Column match vs SDF (BUKAN introspeksi DB): tiap envelope.columns[].name harus ada
  *      di SDF dan tipe konsisten. Mismatch → exit 1. No-PK guard (exit 1).
@@ -46,11 +48,11 @@ const { resolveConfig, printDefaultConfigWarning } = require('../utils/config-re
 const { loadConfig } = require('../dbschema-kit/connection');
 const {
     loadSdf,
-    findTableOrThrow,
     irToColumns,
     getNamespace,
     getPrimaryKey
 } = require('./sdf-reader');
+const { parseSchemaFlag, validateScopeFlags, resolveScope, relDataFilePath } = require('./data-scope');
 const { createDialect, validateIdentifier, placeholder } = require('./dialect-kit');
 const { createExecutor } = require('./db-executor');
 const { decodeValue } = require('./value-codec');
@@ -135,10 +137,12 @@ function matchColumns(envelopeColumns, sdfColumns, tableName) {
 }
 
 /**
- * Push satu tabel SDF dari file envelope JSON `<input>/<qualifiedName>.json` ke DB.
+ * Push satu tabel SDF dari file envelope JSON ke DB. Path input via relDataFilePath
+ * (bersarang `<input>/<schema>/<table>.json` bila ber-schema, flat
+ * `<input>/<table>.json` bila tanpa schema).
  *
  * Mengelola executor-nya sendiri (buat → disconnect di finally) agar isolasi
- * per-tabel jelas dan jalur --all-tables dapat memanggilnya berulang tanpa kebocoran
+ * per-tabel jelas dan jalur multi-schema dapat memanggilnya berulang tanpa kebocoran
  * koneksi. Metadata kolom, namespace, dan PK murni dari IR.
  *
  * @param {Object} ir - IR model SDF satu tabel
@@ -147,24 +151,24 @@ function matchColumns(envelopeColumns, sdfColumns, tableName) {
  * @param {string} ctx.targetDialect - dialect kanonik (untuk output, dirakit caller)
  * @param {Object} ctx.args - argumen ter-parse (storage-path, batch-size)
  * @param {string} ctx.cwd - working directory
- * @returns {Promise<{table: string, rows: number, committed_batches: number}>}
+ * @returns {Promise<{schema: (string|null), table: string, rows: number, committed_batches: number}>}
  */
 async function runOne(ir, ctx) {
     const { config, args, cwd } = ctx;
 
     const sdfColumns = irToColumns(ir);
-    const { qualifiedName } = getNamespace(ir);
+    const { schemaName, qualifiedName } = getNamespace(ir);
     const rawPk = getPrimaryKey(ir);
     const pk = Array.isArray(rawPk) ? rawPk : [];
 
-    // ── a. Derive nama file dari SDF (aturan IDENTIK pull) + baca envelope ─────────
-    // Nama file = {input}/{qualifiedName}.json, turunan murni dari SDF (bukan --table
-    // mentah). Konsisten dengan pull (lihat phase-02b Keputusan K2): tabel ber-schema
-    // → `<schema>.<table>.json`; tanpa schema → `<table>.json`. Single-table:
-    // file-not-found = exit 1 (tak berubah). Jalur --all-tables menyaring file-missing
-    // SEBELUM memanggil runOne (skip-missing), jadi guard ini hanya tercapai pada single.
+    // ── a. Derive nama file dari SDF (aturan IDENTIK pull, relDataFilePath) ────────
+    // Path = {input}/relDataFilePath(ir), turunan MURNI dari SDF (bukan --table mentah
+    // maupun envelope.schema). Tabel ber-schema → bersarang `<schema>/<table>.json`;
+    // tanpa schema → flat `<table>.json`. Single-table: file-not-found = exit 1 (tak
+    // berubah). Jalur --schema/--all-schemas menyaring file-missing SEBELUM memanggil
+    // runOne (skip-missing), jadi guard ini hanya tercapai pada single.
     const inputDir = path.resolve(cwd, args['storage-path']);
-    const inFile = path.join(inputDir, `${qualifiedName}.json`);
+    const inFile = path.join(inputDir, relDataFilePath(ir));
     if (!fs.existsSync(inFile)) {
         const rel = path.relative(cwd, inFile).split(path.sep).join('/');
         throw failWith(`Input file not found: ${rel}`, 1);
@@ -180,6 +184,17 @@ async function runOne(ir, ctx) {
         throw failWith(`Failed to read envelope '${path.relative(cwd, inFile).split(path.sep).join('/')}': ${e.message}`, 1);
     }
 
+    // Cross-check OPSIONAL: path diturunkan dari SDF, bukan envelope. Bila envelope 1.1
+    // membawa `schema` yang berbeda dari schema SDF (mis. file dipindah/diedit manual),
+    // cetak warning informatif (bukan error) — konsisten perlakuan envelope.table.
+    // File 1.0 (tanpa `schema`, undefined) dilewati.
+    if (envelope.schema !== undefined && envelope.schema !== schemaName) {
+        process.stderr.write(
+            `Warning: envelope schema '${envelope.schema}' differs from SDF schema ` +
+            `'${schemaName === null ? '(none)' : schemaName}' for table '${ir.tableName}'\n`
+        );
+    }
+
     // ── b. Column match vs SDF (tanpa introspeksi DB) + no-PK guard ──────────────
     const insertColumns = matchColumns(envelope.columns, sdfColumns, ir.tableName);
 
@@ -233,6 +248,7 @@ async function runOne(ir, ctx) {
 
     // ── e. Ringkasan per-tabel (tanpa command/target_dialect; dirakit caller) ─────
     return {
+        schema: schemaName,
         table: ir.tableName,
         rows: rowCount,
         committed_batches: committedBatches
@@ -240,10 +256,10 @@ async function runOne(ir, ctx) {
 }
 
 /**
- * Jalankan command `data push` (dispatcher: single-table vs --all-tables, append-only).
+ * Jalankan command `data push` (dispatcher: single-table vs multi-schema, append-only).
  * @param {Object} args - argumen ter-parse dari contract
- * @returns {Promise<Object>} ringkasan single { command, table, rows, target_dialect, committed_batches }
- *   atau agregat { command, all_tables, table_count, total_rows, tables: [...], skipped: [...] }
+ * @returns {Promise<Object>} ringkasan single { command, schema, table, rows, target_dialect, committed_batches }
+ *   atau agregat { command, scope, table_count, total_rows, tables: [...], skipped: [...] }
  */
 async function run(args) {
     const cwd = process.cwd();
@@ -267,18 +283,12 @@ async function run(args) {
         throw failWith(e.message, 2);
     }
 
-    // ── 2. Validasi mutual-exclusive --table / --all-tables (SEBELUM SDF/DB) ──────
-    // Arg-parser tidak punya mekanisme XOR lintas-flag (hanya `required` per-flag),
-    // sehingga "tepat satu" ditegakkan di sini. Exit 2 (precondition/usage). Identik
-    // pull-runner Phase 02.
+    // ── 2. Validasi scope flags (SEBELUM SDF/DB) ─────────────────────────────────
+    // Tepat satu dari --table / --schema / --all-schemas (selain itu → exit 2).
+    // Helper bersama dengan pull (data-scope) agar perilaku identik.
+    const schemaList = parseSchemaFlag(args.schema);
+    validateScopeFlags(args, schemaList);
     const hasTable = args.table != null && args.table !== '';
-    const hasAll = args['all-tables'] === true;
-    if (hasTable && hasAll) {
-        throw failWith('Specify exactly one of --table or --all-tables.', 2);
-    }
-    if (!hasTable && !hasAll) {
-        throw failWith('Specify either --table=<name> or --all-tables.', 2);
-    }
 
     // ── 3. Load SDF (SEKALI) ─────────────────────────────────────────────────────
     const schemaPath = args['schema-path'];
@@ -298,12 +308,17 @@ async function run(args) {
         cwd
     };
 
+    // ── 4. Resolusi scope → daftar IR ────────────────────────────────────────────
+    // --table → [ir] (exit 2 bila tak terdaftar/ambigu); --schema → subset (exit 2
+    // bila 0-match); --all-schemas → seluruh IR (boleh kosong → agregat 0 tabel).
+    const subset = resolveScope(models, args, schemaList);
+
     // ── 4a. Jalur --table (single; regresi nol) ──────────────────────────────────
     if (hasTable) {
-        const ir = findTableOrThrow(models, args.table); // throw exitCode=2 bila tak terdaftar/ambigu
-        const per = await runOne(ir, ctx);
+        const per = await runOne(subset[0], ctx);
         const summary = {
             command: 'push',
+            schema: per.schema,
             table: per.table,
             rows: per.rows,
             target_dialect: ctx.targetDialect,
@@ -320,25 +335,28 @@ async function run(args) {
         return summary;
     }
 
-    // ── 4b. Jalur --all-tables (topo-sort FK parent→child, fail-fast Q3, skip-missing) ──
-    // Urutan push diturunkan dari FK SDF: parent (tabel direferensikan) SEBELUM child
-    // agar INSERT child tidak melanggar FK constraint. Siklus → fallback urutan deklarasi.
-    const { ordered, cycle } = topoSortByFk(models);
+    // ── 4b. Jalur --schema/--all-schemas (topo-sort FK parent→child, fail-fast Q3, skip-missing) ──
+    // Urutan push diturunkan dari FK SDF SUBSET (bukan seluruh models): parent (tabel
+    // direferensikan) SEBELUM child agar INSERT child tidak melanggar FK constraint.
+    // Siklus → fallback urutan deklarasi. Catatan (Phase 03): untuk --schema subset, FK
+    // ke parent di luar subset → edge diabaikan table-order; child bisa di-push tanpa
+    // parent → potensi FK error runtime (exit 3), tanpa pre-warning.
+    const scope = schemaList ? 'schema' : 'all-schemas';
+    const subsetMap = new Map(subset.map((ir) => [getNamespace(ir).qualifiedName, ir]));
+    const { ordered, cycle } = topoSortByFk(subsetMap);
     if (cycle) {
         process.stderr.write('FK cycle detected; falling back to declaration order\n');
     }
 
-    // Skip-missing HANYA di --all-tables: tabel tanpa file input dilewati (warning +
-    // catat), bukan error. Catatan (Phase 05): bila parent di-skip namun child ada,
-    // INSERT child dapat melanggar FK → muncul sebagai DB error exit 3 (fail-fast).
+    // Skip-missing HANYA di jalur multi: tabel tanpa file input dilewati (warning +
+    // catat), bukan error. Path input via relDataFilePath (aturan IDENTIK pull).
     const inputDir = path.resolve(cwd, args['storage-path']);
     const tables = [];
     const skipped = [];
     let totalRows = 0;
 
     for (const ir of ordered) {
-        const { qualifiedName } = getNamespace(ir);
-        const inFile = path.join(inputDir, `${qualifiedName}.json`);
+        const inFile = path.join(inputDir, relDataFilePath(ir));
         if (!fs.existsSync(inFile)) {
             process.stderr.write(`Skipped ${ir.tableName}: input file not found\n`);
             skipped.push(ir.tableName);
@@ -357,7 +375,7 @@ async function run(args) {
 
     const aggregate = {
         command: 'push',
-        all_tables: true,
+        scope,
         table_count: tables.length,
         total_rows: totalRows,
         tables,