baucli 1.0.1__py3-none-any.whl

baucli/db/oracle.py

@@ -0,0 +1,1294 @@
+"""BAUCLI — Oracle database extractor.
+
+Uses oracledb (thin mode, no Oracle Client needed).
+Extracts PL/SQL source from DBA_SOURCE/ALL_SOURCE,
+table metadata from DBA_TAB_COLUMNS, DBA_CONSTRAINTS, etc.
+"""
+
+from typing import Optional
+from baucli.db import BaseExtractor, BauConnectionError
+
+
+# ORA-codes mapped to (short friendly message, actionable hint).
+# Keep messages in PT-BR — BAUCLI shipped to BR ops teams.
+_ORA_HINTS = {
+    'ORA-12170': ('Banco de dados inacessível (timeout na conexão).',
+                  'Verifique se o serviço Oracle está no ar e se o host/porta são alcançáveis (firewall, VPN).'),
+    'ORA-12541': ('Listener Oracle não está ativo no host informado.',
+                  'Suba o listener (lsnrctl start) ou confira host/porta.'),
+    'ORA-12514': ('Listener não conhece o serviço solicitado.',
+                  'Confira `service` no perfil baucli — talvez o nome do serviço ou SID esteja errado.'),
+    'ORA-12545': ('Host de destino não pôde ser resolvido.',
+                  'Confira o DNS / hosts ou troque para IP literal.'),
+    'ORA-01017': ('Usuário ou senha inválidos.',
+                  'Revise as credenciais (baucli db edit / config.json).'),
+    'ORA-28000': ('Conta Oracle está bloqueada.',
+                  'DBA precisa rodar: ALTER USER <user> ACCOUNT UNLOCK;'),
+    'ORA-28001': ('Senha Oracle expirou.',
+                  'Renove a senha no banco ou peça ao DBA para redefinir.'),
+    'ORA-12504': ('Listener não recebeu SERVICE_NAME na conexão.',
+                  'Inclua `service` no perfil baucli.'),
+}
+
+
+def _friendly_oracle_error(exc: Exception, host: str, port: int, service: str) -> BauConnectionError:
+    """Map a raw oracledb error to a `BauConnectionError` with friendly text.
+
+    Falls back to the raw message for anything not in `_ORA_HINTS` so unknown
+    failures still surface enough info to debug.
+    """
+    raw = str(exc)
+    target = f"{host}:{port}/{service}"
+    for code, (msg, hint) in _ORA_HINTS.items():
+        if code in raw:
+            return BauConnectionError(
+                f"{code}: {msg} (alvo: {target})", hint=hint, cause=exc)
+    # Generic network / DNS errors not covered by ORA-codes
+    raw_low = raw.lower()
+    if 'name or service not known' in raw_low or 'nodename nor servname' in raw_low:
+        return BauConnectionError(
+            f"Host não resolvível: {host}",
+            hint='Confira DNS, /etc/hosts ou troque para IP literal.',
+            cause=exc)
+    if 'connection refused' in raw_low:
+        return BauConnectionError(
+            f"Conexão recusada por {target}",
+            hint='Banco está no ar? Confira porta e firewall.',
+            cause=exc)
+    return BauConnectionError(
+        f"Falha ao conectar em {target}: {raw.splitlines()[0][:200]}",
+        hint='Rode com --verbose para ver o stack trace completo.',
+        cause=exc)
+
+
+class OracleExtractor(BaseExtractor):
+    """Oracle database extractor using oracledb."""
+
+    engine = "ORACLE"
+
+    def connect(self):
+        import os
+        import oracledb
+        from baucli import __version__
+
+        # ── Oracle Wallet (Autonomous Database over mTLS) ────────────────
+        # When a wallet dir is configured, the DSN is the TNS alias from the
+        # wallet's tnsnames.ora (e.g. mydb_high) and the endpoint/TLS come from
+        # the wallet — host/port are not used.
+        if getattr(self, "wallet_path", None):
+            wdir = os.path.expanduser(self.wallet_path)
+            if not os.path.isdir(wdir):
+                raise BauConnectionError(
+                    f"Wallet não encontrada: {wdir}",
+                    hint="Aponte o wallet para o diretório DESCOMPACTADO do Oracle Wallet "
+                         "(com tnsnames.ora, sqlnet.ora e ewallet.pem).")
+            if not self.service:
+                raise BauConnectionError(
+                    "Conexão por wallet exige o alias TNS em 'service'.",
+                    hint="Use o alias do tnsnames.ora do wallet (ex.: mydb_high) como --service.")
+            kwargs = dict(
+                user=self.user, password=self.password,
+                dsn=self.service,          # TNS alias resolved from tnsnames.ora
+                config_dir=wdir,           # tnsnames.ora / sqlnet.ora
+                wallet_location=wdir,      # ewallet.pem (thin mode mTLS)
+            )
+            if getattr(self, "wallet_password", None):
+                kwargs["wallet_password"] = self.wallet_password
+            try:
+                self._conn = oracledb.connect(**kwargs)
+            except oracledb.Error as e:
+                emsg = str(e)
+                # Thin mode needs ewallet.pem; an SSO-only (auto-login) wallet
+                # requires thick mode + Instant Client. Try that fallback.
+                if ('thick' in emsg.lower() or 'DPY-3001' in emsg or 'DPY-6005' in emsg
+                        or 'ewallet.pem' in emsg.lower()):
+                    try:
+                        oracledb.init_oracle_client(
+                            lib_dir=os.environ.get("ORACLE_INSTANT_CLIENT_DIR") or None,
+                            config_dir=wdir)
+                    except oracledb.Error as init_err:
+                        if 'DPI-1072' not in str(init_err):
+                            raise BauConnectionError(
+                                "Wallet requer modo thick (SSO/auto-login) mas o Instant "
+                                f"Client não iniciou: {init_err}",
+                                hint="Baixe o wallet COM 'ewallet.pem' e informe a senha do "
+                                     "wallet (--wallet-password) para o modo thin, ou defina "
+                                     "ORACLE_INSTANT_CLIENT_DIR para o modo thick.",
+                                cause=init_err) from init_err
+                    try:
+                        self._conn = oracledb.connect(
+                            user=self.user, password=self.password, dsn=self.service)
+                    except oracledb.Error as e2:
+                        raise BauConnectionError(
+                            f"Falha ao conectar via wallet (alias {self.service}): {e2}",
+                            hint="Confira o alias TNS, a senha do wallet e o usuário/senha do banco.",
+                            cause=e2) from e2
+                else:
+                    raise BauConnectionError(
+                        f"Falha ao conectar via wallet (alias {self.service}): {e}",
+                        hint="Confira o alias TNS no tnsnames.ora, a senha do wallet "
+                             "(--wallet-password) e o usuário/senha do banco.",
+                        cause=e) from e
+            except OSError as e:
+                raise BauConnectionError(
+                    f"Erro de rede ao alcançar o endpoint do wallet: {e}",
+                    hint="Verifique conectividade/porta 1522 (ADB) e o sqlnet.ora do wallet.",
+                    cause=e) from e
+
+            cur = self._conn.cursor()
+            cur.callproc("DBMS_APPLICATION_INFO.SET_MODULE", [f"BAUCLI v{__version__}", "IDLE"])
+            cur.callproc("DBMS_APPLICATION_INFO.SET_CLIENT_INFO", ["BAUCLI"])
+            cur.close()
+            return
+
+        dsn = f"{self.host}:{self.port}/{self.service}"
+
+        # Try thin mode first, fall back to thick mode for NNE (Native Network Encryption).
+        # Thick mode needs Oracle Instant Client; pass its path via ORACLE_INSTANT_CLIENT_DIR
+        # (or rely on the system-default LD_LIBRARY_PATH).
+        try:
+            self._conn = oracledb.connect(user=self.user, password=self.password, dsn=dsn)
+        except oracledb.Error as e:
+            err_msg = str(e)
+            if 'thick mode' in err_msg.lower() or 'DPY-3001' in err_msg or 'DPY-6005' in err_msg:
+                ic_dir = os.environ.get("ORACLE_INSTANT_CLIENT_DIR") or None
+                try:
+                    oracledb.init_oracle_client(lib_dir=ic_dir)
+                except oracledb.Error as init_err:
+                    if 'DPI-1072' not in str(init_err):  # already initialized
+                        raise BauConnectionError(
+                            f"Banco exige modo thick mas Instant Client não iniciou: {init_err}",
+                            hint='Defina ORACLE_INSTANT_CLIENT_DIR apontando para o Instant Client.',
+                            cause=init_err) from init_err
+                try:
+                    self._conn = oracledb.connect(
+                        user=self.user, password=self.password, dsn=dsn)
+                except oracledb.Error as e2:
+                    raise _friendly_oracle_error(e2, self.host, self.port, self.service) from e2
+            else:
+                raise _friendly_oracle_error(e, self.host, self.port, self.service) from e
+        except OSError as e:
+            # Socket-level errors (gaierror, ConnectionRefusedError, etc.) before oracledb
+            # even gets to send a TNS packet. These come from create_connection().
+            raise _friendly_oracle_error(e, self.host, self.port, self.service) from e
+
+        # Identify BAUCLI in Oracle sessions
+        cur = self._conn.cursor()
+        cur.callproc("DBMS_APPLICATION_INFO.SET_MODULE", [f"BAUCLI v{__version__}", "IDLE"])
+        cur.callproc("DBMS_APPLICATION_INFO.SET_CLIENT_INFO", [f"BAUCLI"])
+        cur.close()
+
+    def disconnect(self):
+        if self._conn:
+            try:
+                self._conn.close()
+            except Exception:
+                pass
+            self._conn = None
+
+    def run_readonly(self, sql: str, max_rows: int = 5) -> dict:
+        """Execute a SELECT read-only and return {rowcount, sample, ms, error}.
+
+        Used by `baucli semantic verify` to prove a library query runs against
+        the real DB. Refuses anything that is not a single SELECT/WITH, and runs
+        inside a READ ONLY transaction so it can never mutate. Never raises —
+        failures come back as {error: ...} so the caller can post them back.
+        """
+        import time
+        text = (sql or "").strip().rstrip(";")
+        head = text.lstrip("(").lstrip().upper()
+        if not (head.startswith("SELECT") or head.startswith("WITH")):
+            return {"rowcount": None, "sample": None, "ms": None,
+                    "error": "recusado: apenas SELECT/WITH é permitido"}
+        cur = self._conn.cursor()
+        t0 = time.time()
+        try:
+            try:
+                cur.execute("SET TRANSACTION READ ONLY")
+            except Exception:
+                pass
+            cur.execute(text)
+            rows = cur.fetchmany(max_rows + 1) or []
+            cols = [d[0] for d in (cur.description or [])]
+            ms = int((time.time() - t0) * 1000)
+            shown = rows[:max_rows]
+            def _fmt(v):
+                s = "NULL" if v is None else str(v)
+                return s if len(s) <= 60 else s[:57] + "…"
+            sample = " | ".join(cols) + "\n" + "\n".join(
+                ", ".join(_fmt(v) for v in r) for r in shown) if shown else "(0 rows)"
+            return {"rowcount": len(rows) - 1 if len(rows) > max_rows else len(rows),
+                    "sample": sample[:2000], "ms": ms, "error": None}
+        except Exception as e:
+            return {"rowcount": None, "sample": None,
+                    "ms": int((time.time() - t0) * 1000),
+                    "error": str(e)[:2000]}
+        finally:
+            try:
+                self._conn.rollback()   # end the read-only transaction
+                cur.close()
+            except Exception:
+                pass
+
+    def test_connection(self) -> dict:
+        self._set_action("TEST_CONNECTION")
+        cur = self._conn.cursor()
+        cur.execute("SELECT BANNER_FULL FROM V$VERSION WHERE ROWNUM=1")
+        banner = cur.fetchone()
+        cur.execute("SELECT SYS_CONTEXT('USERENV','DB_NAME') FROM DUAL")
+        db_name = cur.fetchone()
+        cur.execute("SELECT SYS_CONTEXT('USERENV','CURRENT_SCHEMA') FROM DUAL")
+        current_schema = cur.fetchone()
+        cur.close()
+        return {
+            "status": "ok",
+            "engine": "ORACLE",
+            "version": banner[0] if banner else "Unknown",
+            "db_name": db_name[0] if db_name else "Unknown",
+            "current_schema": current_schema[0] if current_schema else "Unknown",
+        }
+
+    def get_native_identifier(self) -> Optional[str]:
+        try:
+            cur = self._conn.cursor()
+            cur.execute("SELECT DBID FROM V$DATABASE")
+            row = cur.fetchone()
+            cur.close()
+            return str(row[0]) if row else None
+        except Exception:
+            return None
+
+    def _get_source_view(self, schema: str) -> str:
+        """Determine if we can use DBA_SOURCE or fall back to ALL_SOURCE."""
+        cur = self._conn.cursor()
+        try:
+            cur.execute("SELECT 1 FROM DBA_SOURCE WHERE ROWNUM=1")
+            cur.close()
+            return "DBA_SOURCE"
+        except Exception:
+            cur.close()
+            return "ALL_SOURCE"
+
+    def _get_tab_view(self, schema: str) -> str:
+        """Determine if we can use DBA_* or ALL_* views."""
+        cur = self._conn.cursor()
+        try:
+            cur.execute("SELECT 1 FROM DBA_TABLES WHERE ROWNUM=1")
+            cur.close()
+            return "DBA"
+        except Exception:
+            cur.close()
+            return "ALL"
+
+    def _set_action(self, action: str):
+        """Set DBMS_APPLICATION_INFO.SET_ACTION for V$SESSION monitoring."""
+        try:
+            cur = self._conn.cursor()
+            cur.callproc("DBMS_APPLICATION_INFO.SET_ACTION", [action])
+            cur.close()
+        except Exception:
+            pass
+
+    def count_objects(self, schema: str) -> int:
+        cur = self._conn.cursor()
+        try:
+            cur.execute("SELECT 1 FROM DBA_OBJECTS WHERE ROWNUM=1")
+            prefix = "DBA"
+        except Exception:
+            prefix = "ALL"
+        cur.execute(f"""
+            SELECT COUNT(DISTINCT OBJECT_NAME || '.' || OBJECT_TYPE) FROM {prefix}_OBJECTS
+            WHERE OWNER = :schema AND OBJECT_TYPE IN ('PACKAGE','PACKAGE BODY','FUNCTION','PROCEDURE','TRIGGER')
+            AND OBJECT_NAME NOT LIKE 'BIN$%' AND OBJECT_NAME NOT LIKE 'SYS_%'
+            -- match extract_objects: it syncs only VALID objects (invalids are skipped),
+            -- so the scope count must exclude INVALID too (else scope > synced).
+            AND STATUS = 'VALID'
+            -- and BAU's own generated lookup functions (FNC_BAU_*) are never documented.
+            AND OBJECT_NAME NOT LIKE 'FNC_BAU_%'
+        """, {"schema": schema.upper()})
+        cnt = cur.fetchone()[0]
+        cur.close()
+        return cnt
+
+    def count_tables(self, schema: str) -> int:
+        cur = self._conn.cursor()
+        try:
+            cur.execute("SELECT 1 FROM DBA_OBJECTS WHERE ROWNUM=1")
+            prefix = "DBA"
+        except Exception:
+            prefix = "ALL"
+        cur.execute(f"""
+            SELECT COUNT(*) FROM {prefix}_OBJECTS
+            WHERE OWNER = :schema AND OBJECT_TYPE IN ('TABLE','VIEW','MATERIALIZED VIEW')
+            AND OBJECT_NAME NOT LIKE 'BIN$%' AND OBJECT_NAME NOT LIKE 'SYS_%'
+            AND OBJECT_NAME NOT LIKE 'MLOG$%' AND OBJECT_NAME NOT LIKE 'RUPD$%'
+            -- match extract_tables' exclusion set (else scope > synced):
+            -- 23ai annotation helper tables + BAU's own generated helper tables
+            -- (BAU_DOMAINS/BAU_DOMAIN_VALUES/BAU_DOMAIN_BINDINGS/BAU_ERROR_MESSAGES).
+            AND OBJECT_NAME NOT LIKE 'ANNOTATIONS_%'
+            -- 23ai/APEX annotation helper objects: METADATA_ANNOTATIONS* AND
+            -- METADATA_PREBUILT_ANNOTATIONS (a view). METADATA%ANNOTATIONS% cobre
+            -- toda a família (METADATA_<x>_ANNOTATIONS*).
+            AND OBJECT_NAME NOT LIKE 'METADATA%ANNOTATIONS%'
+            AND OBJECT_NAME NOT LIKE 'BAU_%'
+        """, {"schema": schema.upper()})
+        cnt = cur.fetchone()[0]
+        cur.close()
+        return cnt
+
+    def extract_dependencies(self, schema: str) -> list:
+        """Extract intra-schema object dependencies from {DBA|ALL}_DEPENDENCIES.
+
+        Roda no CLIENTE, que enxerga 100% das proprias dependencias (o dono do
+        schema ve PACKAGE BODY -> TABLE etc). Enviado no payload do /sync/batch;
+        o servidor BAU NUNCA le o dicionario local do cliente. Fase 2 = escopo
+        intra-schema (owner = referenced_owner); cross-schema/dblink fica p/ depois.
+        """
+        cur = self._conn.cursor()
+        try:
+            cur.execute("SELECT 1 FROM DBA_DEPENDENCIES WHERE ROWNUM=1")
+            prefix = "DBA"
+        except Exception:
+            prefix = "ALL"
+        s = schema.upper()
+        cur.execute(f"""
+            SELECT owner, name, type, referenced_owner, referenced_name,
+                   referenced_type, dependency_type
+              FROM {prefix}_DEPENDENCIES
+             WHERE owner = :s AND referenced_owner = :s
+               AND name <> referenced_name
+               AND referenced_type IN ('TABLE','VIEW','MATERIALIZED VIEW',
+                     'PACKAGE','PACKAGE BODY','PROCEDURE','FUNCTION','TRIGGER','TYPE')
+               AND name NOT LIKE 'BIN$%' AND referenced_name NOT LIKE 'BIN$%'
+        """, {"s": s})
+        rows = cur.fetchall()
+        cur.close()
+        return [
+            {"owner": r[0], "name": r[1], "type": r[2],
+             "ref_owner": r[3], "ref_name": r[4],
+             "ref_type": r[5], "dep_type": r[6]}
+            for r in rows
+        ]
+
+    def extract_sequences(self, schema: str) -> list:
+        """Extract named sequences from {DBA|ALL}_SEQUENCES for DOCSEQ.
+
+        Exclui identity system sequences (ISEQ$$) e recycle bin (BIN$) — o
+        vinculo de identity columns e descoberto no servidor via DATA_DEFAULT
+        (ISEQ$$...nextval). Enviado numa chamada dedicada do /sync/batch
+        (objects=[]); o servidor persiste os metadados fisicos (SYNC_FROM_JSON)
+        e roda PKG_BAU_DOCSEQ.DISCOVER.
+        """
+        cur = self._conn.cursor()
+        try:
+            cur.execute("SELECT 1 FROM DBA_SEQUENCES WHERE ROWNUM=1")
+            prefix = "DBA"
+        except Exception:
+            prefix = "ALL"
+        s = schema.upper()
+        cur.execute(f"""
+            SELECT SEQUENCE_OWNER, SEQUENCE_NAME, MIN_VALUE, MAX_VALUE, INCREMENT_BY,
+                   CYCLE_FLAG, ORDER_FLAG, CACHE_SIZE, LAST_NUMBER
+              FROM {prefix}_SEQUENCES
+             WHERE SEQUENCE_OWNER = :s
+               AND SEQUENCE_NAME NOT LIKE 'ISEQ$$%'
+               AND SEQUENCE_NAME NOT LIKE 'BIN$%'
+        """, {"s": s})
+        rows = cur.fetchall()
+        cur.close()
+
+        def _n(v):
+            return int(v) if v is not None else None
+
+        return [
+            {"owner": r[0], "sequence_name": r[1],
+             "min_value": _n(r[2]), "max_value": _n(r[3]),
+             "increment_by": _n(r[4]),
+             "cycle_flag": (r[5] or "N"), "order_flag": (r[6] or "N"),
+             "cache_size": _n(r[7]), "last_number": _n(r[8])}
+            for r in rows
+        ]
+
+    def extract_row_counts(self, schema: str, name_filter=None) -> dict:
+        """Lightweight num_rows snapshot (one dictionary query) — the baseline
+        row-count 'idea' captured on every sync (source=DEV, since baucli
+        normally runs against the dev environment). Read-only, no data scan.
+
+        name_filter: optional collection of table names (scope sets) — the
+        snapshot covers ONLY those tables; a scoped project must not push a
+        whole-ERP profile (thousands of rows) to /profile/ingest."""
+        s = schema.upper()
+        cur = self._conn.cursor()
+        try:
+            cur.execute("SELECT 1 FROM DBA_TABLES WHERE ROWNUM=1")
+            prefix = "DBA"
+        except Exception:
+            prefix = "ALL"
+        params = {"s": s}
+        name_clause = ""
+        if isinstance(name_filter, (list, set, tuple)):
+            names = sorted({str(n).upper() for n in name_filter})
+            if not names:
+                cur.close()
+                return {"schema": s, "source": "DEV", "tables": []}
+            name_clause = "AND TABLE_NAME IN (%s)" % ",".join(
+                f":rc{i}" for i in range(len(names)))
+            params.update({f"rc{i}": n for i, n in enumerate(names)})
+        cur.execute(f"SELECT TABLE_NAME, NUM_ROWS FROM {prefix}_TABLES WHERE OWNER = :s "
+                    f"{name_clause}", params)
+        tables = [{"name": r[0], "num_rows": r[1]} for r in cur.fetchall()]
+        cur.close()
+        return {"schema": s, "source": "DEV", "tables": tables}
+
+    def extract_profile(self, schema: str) -> dict:
+        """Data profile from the client DB optimizer stats (Phase 4).
+
+        Per table: NUM_ROWS; per column: NUM_DISTINCT, NUM_NULLS, NULL_PCT,
+        SAMPLE_SIZE, HISTOGRAM and the top frequent values (from
+        {DBA|ALL}_TAB_HISTOGRAMS, decoded endpoint_actual_value only). Read-only
+        on the dictionary; sent to /profile/ingest. Never scans table data."""
+        s = schema.upper()
+        cur = self._conn.cursor()
+        try:
+            cur.execute("SELECT 1 FROM DBA_TABLES WHERE ROWNUM=1")
+            prefix = "DBA"
+        except Exception:
+            prefix = "ALL"
+
+        cur.execute(f"SELECT TABLE_NAME, NUM_ROWS FROM {prefix}_TABLES WHERE OWNER = :s",
+                    {"s": s})
+        num_rows = {r[0]: r[1] for r in cur.fetchall()}
+
+        cols = {}
+        cur.execute(f"""
+            SELECT TABLE_NAME, COLUMN_NAME, NUM_DISTINCT, NUM_NULLS, SAMPLE_SIZE, HISTOGRAM
+              FROM {prefix}_TAB_COLUMNS WHERE OWNER = :s
+        """, {"s": s})
+        for tn, cn, nd, nn, ss, hist in cur.fetchall():
+            nr = num_rows.get(tn)
+            null_pct = round(nn / nr * 100, 2) if nr and nn is not None and nr > 0 else None
+            cols.setdefault(tn, []).append({
+                "name": cn, "num_distinct": nd, "num_nulls": nn, "null_pct": null_pct,
+                "sample_size": ss, "histogram": hist, "top_values": None,
+            })
+
+        # top frequent values from frequency-style histograms (decoded only)
+        from collections import defaultdict
+        buckets = defaultdict(list)
+        prev = {}
+        cur.execute(f"""
+            SELECT TABLE_NAME, COLUMN_NAME, endpoint_actual_value, endpoint_number
+              FROM {prefix}_TAB_HISTOGRAMS
+             WHERE OWNER = :s AND endpoint_actual_value IS NOT NULL
+             ORDER BY TABLE_NAME, COLUMN_NAME, endpoint_number
+        """, {"s": s})
+        for tn, cn, val, epn in cur.fetchall():
+            key = (tn, cn)
+            cnt = (epn or 0) - prev.get(key, 0)
+            prev[key] = epn or 0
+            buckets[key].append((val, cnt))
+        for (tn, cn), vals in buckets.items():
+            vals.sort(key=lambda x: x[1], reverse=True)
+            top = " | ".join(f"{v}:{c}" for v, c in vals[:6])[:2000]
+            for cd in cols.get(tn, []):
+                if cd["name"] == cn:
+                    cd["top_values"] = top
+                    break
+        cur.close()
+
+        tables = [{"name": tn, "num_rows": num_rows.get(tn), "columns": cols[tn]}
+                  for tn in sorted(cols)]
+        return {"schema": s, "tables": tables}
+
+    def extract_objects(self, schema: str, since_date: str = None, on_progress=None,
+                        name_filter: str = None, include_invalid: bool = False) -> list:
+        """Extract PL/SQL objects from DBA_SOURCE/ALL_SOURCE.
+
+        Args:
+            schema: Schema/owner name
+            since_date: If provided, only extract objects modified since this date (ISO format)
+            name_filter: If provided, restrict to OBJECT_NAME = UPPER(name_filter).
+                A collection (list/set/tuple) restricts to OBJECT_NAME IN (...) —
+                used by scope sets; empty collection returns [].
+            include_invalid: If True, include INVALID objects too (with status='INVALID'
+                and without source body). Used by `baucli compare` to surface broken
+                objects instead of silently skipping them; default False keeps
+                normal sync behavior — sync never uploads invalid source.
+        """
+        self._set_action(f"EXTRACT_OBJECTS:{schema}")
+        src_view = self._get_source_view(schema)
+        prefix = "DBA" if "DBA" in src_view else "ALL"
+        schema_upper = schema.upper()
+
+        cur = self._conn.cursor()
+
+        # Build WHERE clause
+        params = {"schema": schema_upper}
+        date_filter = ""
+        if since_date:
+            date_filter = "AND o.LAST_DDL_TIME >= TO_DATE(:since_date, 'YYYY-MM-DD\"T\"HH24:MI:SS')"
+            params["since_date"] = since_date
+        name_clause = ""
+        if isinstance(name_filter, (list, set, tuple)):
+            # Scope sets pass a collection: extract ONLY these objects — the
+            # catalog query filters server-side, so a scoped sync never walks
+            # the rest of a huge ERP schema.
+            names = sorted({str(n).upper() for n in name_filter})
+            if not names:
+                return []
+            name_clause = "AND o.OBJECT_NAME IN (%s)" % ",".join(
+                f":nf{i}" for i in range(len(names)))
+            params.update({f"nf{i}": n for i, n in enumerate(names)})
+        elif name_filter:
+            name_clause = "AND o.OBJECT_NAME = :obj_name"
+            params["obj_name"] = name_filter.upper()
+
+        # Get distinct objects (include INVALID when asked, e.g. for compare drift)
+        status_clause = "" if include_invalid else "AND o.STATUS = 'VALID'"
+        cur.execute(f"""
+            SELECT DISTINCT o.OBJECT_TYPE, o.OBJECT_NAME, o.STATUS,
+                   TO_CHAR(o.LAST_DDL_TIME, 'YYYY-MM-DD"T"HH24:MI:SS') AS LAST_DDL
+            FROM   {prefix}_OBJECTS o
+            WHERE  o.OWNER = :schema
+            AND    o.OBJECT_TYPE IN ('PACKAGE','PACKAGE BODY','FUNCTION','PROCEDURE','TRIGGER')
+            AND    o.OBJECT_NAME NOT LIKE 'BIN$%%'
+            AND    o.OBJECT_NAME NOT LIKE 'SYS_%%'
+            -- BAU never documents its OWN generated lookup functions
+            -- (FNC_BAU_ERROR_MSG, FNC_BAU_DOMAIN_LABEL) emitted into the client
+            -- schema by the baucli provision/apply scripts.
+            AND    o.OBJECT_NAME NOT LIKE 'FNC_BAU_%%'
+            {status_clause}
+            {name_clause}
+            {date_filter}
+            ORDER BY o.OBJECT_TYPE, o.OBJECT_NAME
+        """, params)
+
+        obj_list = cur.fetchall()
+        total_obj = len(obj_list)
+        result = []
+
+        for idx, (obj_type, obj_name, obj_status, last_ddl) in enumerate(obj_list):
+            if on_progress:
+                on_progress(idx + 1, total_obj, obj_name)
+
+            # For INVALID objects we still emit a stub entry (no source) so
+            # drift can flag them; only the source body is skipped.
+            if obj_status != "VALID":
+                result.append({
+                    "name": obj_name,
+                    "type": obj_type,
+                    "source": None,
+                    "last_ddl": last_ddl,
+                    "status": obj_status,
+                })
+                continue
+
+            # Get source lines
+            cur.execute(f"""
+                SELECT TEXT FROM {src_view}
+                WHERE  OWNER = :schema AND NAME = :name AND TYPE = :otype
+                ORDER BY LINE
+            """, {"schema": schema_upper, "name": obj_name, "otype": obj_type})
+
+            lines = [row[0] for row in cur.fetchall()]
+            if not lines:
+                continue
+
+            source = "".join(lines)
+
+            # DBA_SOURCE.text already starts with "<TYPE> name ..." for every
+            # supported object — only the CREATE OR REPLACE wrapper is missing.
+            # Earlier versions prepended the full "<TYPE> {schema}.{name}\n" on
+            # top, duplicating the type+name; Oracle tolerated it for PACKAGE
+            # but rejected for TRIGGER (ORA-04071) and FUNCTION/PROCEDURE.
+            # Matches the server-side PKG_BAU_DOCPL_CORE.SYNC_OBJECTS behavior.
+            if obj_type in ("PACKAGE", "PACKAGE BODY", "FUNCTION", "PROCEDURE", "TRIGGER"):
+                source = f"CREATE OR REPLACE {source}"
+
+            result.append({
+                "name": obj_name,
+                "type": obj_type,
+                "source": source,
+                "last_ddl": last_ddl,
+                "status": "VALID",
+            })
+
+        # Bulk-fetch subprograms (PROCEDURE/FUNCTION inside packages) — one query for
+        # the whole schema, then attach to the matching parent. Type is detected via
+        # DBA_ARGUMENTS (POSITION=0 exists ⇒ FUNCTION; else PROCEDURE).
+        # With a small extracted set (scoped sync / --object), BOTH dictionary
+        # scans are restricted to the extracted names — ALL_PROCEDURES/
+        # ALL_ARGUMENTS schema-wide on a big ERP cost minutes for 4 objects.
+        proc_view = "DBA_PROCEDURES" if prefix == "DBA" else "ALL_PROCEDURES"
+        arg_view  = "DBA_ARGUMENTS"  if prefix == "DBA" else "ALL_ARGUMENTS"
+        pkg_names = sorted({o["name"] for o in result
+                            if o["type"] in ("PACKAGE", "PACKAGE BODY")})
+        sa_names  = sorted({o["name"] for o in result
+                            if o["type"] in ("FUNCTION", "PROCEDURE")})
+        _small = 0 < (len(pkg_names) + len(sa_names)) <= 500
+
+        sub_clause = ""
+        sub_params = {"schema": schema_upper}
+        if _small and pkg_names:
+            sub_clause = "AND p.OBJECT_NAME IN (%s)" % ",".join(
+                f":sp{i}" for i in range(len(pkg_names)))
+            sub_params.update({f"sp{i}": n for i, n in enumerate(pkg_names)})
+
+        arg_clause = ""
+        arg_params = {"schema": schema_upper}
+        if _small:
+            ors = []
+            if pkg_names:
+                ors.append("a.PACKAGE_NAME IN (%s)" % ",".join(
+                    f":ap{i}" for i in range(len(pkg_names))))
+                arg_params.update({f"ap{i}": n for i, n in enumerate(pkg_names)})
+            if sa_names:
+                ors.append("(a.PACKAGE_NAME IS NULL AND a.OBJECT_NAME IN (%s))"
+                           % ",".join(f":as{i}" for i in range(len(sa_names))))
+                arg_params.update({f"as{i}": n for i, n in enumerate(sa_names)})
+            arg_clause = "AND (%s)" % " OR ".join(ors) if ors else "AND 1=0"
+
+        try:
+            subs_by_pkg = {}
+            if not _small or pkg_names:
+                cur2 = self._conn.cursor()
+                cur2.execute(f"""
+                    SELECT p.OBJECT_NAME, p.PROCEDURE_NAME,
+                           CASE WHEN EXISTS (
+                                SELECT 1 FROM {arg_view} a
+                                 WHERE a.OWNER        = p.OWNER
+                                   AND a.PACKAGE_NAME = p.OBJECT_NAME
+                                   AND a.OBJECT_NAME  = p.PROCEDURE_NAME
+                                   AND a.POSITION     = 0
+                            ) THEN 'FUNCTION' ELSE 'PROCEDURE' END AS SUBPROG_TYPE
+                      FROM {proc_view} p
+                     WHERE p.OWNER          = :schema
+                       AND p.PROCEDURE_NAME IS NOT NULL
+                       AND p.OBJECT_TYPE    IN ('PACKAGE','PACKAGE BODY')
+                       {sub_clause}
+                     ORDER BY p.OBJECT_NAME, p.PROCEDURE_NAME
+                """, sub_params)
+                seen = set()
+                for pkg_name, sub_name, sub_type in cur2.fetchall():
+                    key = (pkg_name, sub_name)
+                    if key in seen:
+                        continue  # collapse overloads to first occurrence
+                    seen.add(key)
+                    subs_by_pkg.setdefault(pkg_name, []).append({
+                        "name": sub_name, "type": sub_type,
+                    })
+                cur2.close()
+
+            # Bulk-fetch parameters (restricted to the extracted names when
+            # the set is small). Bucket by (package_name, object_name) so we
+            # can attach to top-level FUNCTION/PROCEDURE and to package
+            # subprograms.
+            cur3 = self._conn.cursor()
+            cur3.execute(f"""
+                SELECT a.PACKAGE_NAME, a.OBJECT_NAME, a.POSITION,
+                       a.ARGUMENT_NAME, a.IN_OUT, a.DATA_TYPE, a.DEFAULTED
+                  FROM {arg_view} a
+                 WHERE a.OWNER      = :schema
+                   AND a.DATA_LEVEL = 0
+                   {arg_clause}
+                 ORDER BY a.PACKAGE_NAME NULLS FIRST,
+                          a.OBJECT_NAME, a.POSITION
+            """, arg_params)
+            params_by_key = {}
+            for pkg, obj, pos, arg_name, in_out, data_type, defaulted in cur3.fetchall():
+                key = (pkg, obj)  # pkg may be None for standalone proc/func
+                if pos == 0 and arg_name is None:
+                    param_type = "RETURN"
+                    param_name = "(return)"
+                else:
+                    param_type = in_out or "IN"
+                    param_name = arg_name
+                params_by_key.setdefault(key, []).append({
+                    "name": param_name,
+                    "type": param_type,
+                    "data_type": data_type,
+                    "position": pos,
+                    "defaulted": defaulted or "N",
+                })
+            cur3.close()
+
+            # Attach params to top-level FUNCTION/PROCEDURE
+            for obj in result:
+                if obj["type"] in ("FUNCTION", "PROCEDURE"):
+                    obj["params"] = params_by_key.get((None, obj["name"]), [])
+
+            # Attach subprograms (with their params) to PACKAGE/PACKAGE BODY
+            for obj in result:
+                if obj["type"] in ("PACKAGE", "PACKAGE BODY"):
+                    subs = subs_by_pkg.get(obj["name"])
+                    if subs:
+                        for sp in subs:
+                            sp["params"] = params_by_key.get(
+                                (obj["name"], sp["name"]), []
+                            )
+                        obj["subprograms"] = subs
+        except Exception:
+            # Subprogram/params extraction failure must never block the sync — best-effort.
+            pass
+
+        cur.close()
+        return result
+
+    def extract_tables(self, schema: str, since_date: str = None, on_progress=None,
+                       name_filter: str = None) -> list:
+        """Extract table metadata from DBA/ALL views.
+
+        Args:
+            schema: Schema/owner name
+            since_date: If provided, only extract tables modified since this date (ISO format)
+            name_filter: If provided, restrict to TABLE_NAME = UPPER(name_filter).
+                A collection (list/set/tuple) restricts to TABLE_NAME IN (...) —
+                used by scope sets; empty collection returns [].
+        """
+        self._set_action(f"EXTRACT_TABLES:{schema}")
+        prefix = self._get_tab_view(schema)
+        schema_upper = schema.upper()
+
+        cur = self._conn.cursor()
+
+        # Build WHERE clause
+        params = {"schema": schema_upper}
+        date_filter = ""
+        if since_date:
+            date_filter = "AND o.LAST_DDL_TIME >= TO_DATE(:since_date, 'YYYY-MM-DD\"T\"HH24:MI:SS')"
+            params["since_date"] = since_date
+        name_clause = ""
+        if isinstance(name_filter, (list, set, tuple)):
+            # Scope sets pass a collection: extract ONLY these tables/views.
+            names = sorted({str(n).upper() for n in name_filter})
+            if not names:
+                return []
+            name_clause = "AND o.OBJECT_NAME IN (%s)" % ",".join(
+                f":tf{i}" for i in range(len(names)))
+            params.update({f"tf{i}": n for i, n in enumerate(names)})
+        elif name_filter:
+            name_clause = "AND o.OBJECT_NAME = :tbl_name"
+            params["tbl_name"] = name_filter.upper()
+
+        # Get tables AND views with DDL time.
+        # NOTE: use o.OBJECT_NAME as the name (always populated). Using
+        # t.TABLE_NAME dropped every VIEW: the _TABLES join only matches
+        # OBJECT_TYPE='TABLE', so views came back with a NULL name and were
+        # silently discarded downstream (tables synced, views did not).
+        cur.execute(f"""
+            SELECT o.OBJECT_NAME AS TABLE_NAME,
+                   TO_CHAR(o.LAST_DDL_TIME, 'YYYY-MM-DD"T"HH24:MI:SS') AS LAST_DDL,
+                   tc.COMMENTS AS TABLE_COMMENT,
+                   o.OBJECT_TYPE
+            FROM   {prefix}_OBJECTS o
+            LEFT JOIN {prefix}_TABLES t ON t.OWNER = o.OWNER AND t.TABLE_NAME = o.OBJECT_NAME AND o.OBJECT_TYPE = 'TABLE'
+            LEFT JOIN {prefix}_VIEWS  v ON v.OWNER = o.OWNER AND v.VIEW_NAME  = o.OBJECT_NAME AND o.OBJECT_TYPE = 'VIEW'
+            LEFT JOIN {prefix}_TAB_COMMENTS tc ON tc.OWNER = o.OWNER AND tc.TABLE_NAME = o.OBJECT_NAME
+            WHERE  o.OWNER = :schema
+            AND    o.OBJECT_TYPE IN ('TABLE', 'VIEW', 'MATERIALIZED VIEW')
+            AND    o.OBJECT_NAME NOT LIKE 'BIN$%%'
+            AND    o.OBJECT_NAME NOT LIKE 'SYS_%%'
+            AND    o.OBJECT_NAME NOT LIKE 'MLOG$%%'
+            AND    o.OBJECT_NAME NOT LIKE 'RUPD$%%'
+            AND    o.OBJECT_NAME NOT LIKE 'ANNOTATIONS_%%'
+            -- 23ai/APEX annotation helper objects: METADATA_ANNOTATIONS* +
+            -- METADATA_PREBUILT_ANNOTATIONS (view). METADATA%ANNOTATIONS% cobre a família.
+            AND    o.OBJECT_NAME NOT LIKE 'METADATA%%ANNOTATIONS%%'
+            -- BAU never documents its OWN generated helper tables (domain values +
+            -- error-message lookup): BAU_DOMAINS/BAU_DOMAIN_VALUES/BAU_DOMAIN_BINDINGS/
+            -- BAU_ERROR_MESSAGES, emitted into the client schema by the baucli
+            -- provision/apply scripts. BAU_ is the platform's reserved prefix.
+            AND    o.OBJECT_NAME NOT LIKE 'BAU_%%'
+            {name_clause}
+            {date_filter}
+            ORDER BY o.OBJECT_TYPE, o.OBJECT_NAME
+        """, params)
+
+        tables = cur.fetchall()
+        total_tbl = len(tables)
+        result = []
+
+        if total_tbl == 0:
+            cur.close()
+            return result
+
+        CHUNK = 500
+
+        # ═══ Pre-load columns in chunks ═══
+        all_columns = {}
+        table_names = [t[0] for t in tables if t[0]]
+        col_count = 0
+
+        # For small table sets (scoped sync / --table) the shared pre-loads
+        # below (comments/PKs/constraints/indexes) must NOT scan the whole
+        # schema: on a 6000-table ERP those dictionary queries cost minutes
+        # for a 10-table recorte. Restrict them by TABLE_NAME IN (...).
+        _pre_names = table_names if 0 < len(table_names) <= CHUNK else []
+        _pre_params = {f"pt{i}": tn for i, tn in enumerate(_pre_names)}
+
+        def _pre_clause(alias: str = "") -> str:
+            if not _pre_names:
+                return ""
+            col = (alias + "." if alias else "") + "TABLE_NAME"
+            return "AND %s IN (%s)" % (
+                col, ",".join(f":pt{i}" for i in range(len(_pre_names))))
+
+        import time as _time
+        total_chunks = (len(table_names) + CHUNK - 1) // CHUNK
+        chunk_times = []
+
+        for ci, cs in enumerate(range(0, len(table_names), CHUNK)):
+            chunk = table_names[cs:cs + CHUNK]
+            t0 = _time.time()
+
+            eta = ""
+            if len(chunk_times) >= 2:
+                avg = sum(chunk_times) / len(chunk_times)
+                remaining = total_chunks - ci
+                eta_s = int(remaining * avg)
+                eta = f" ETA {eta_s//60}m{eta_s%60:02d}s" if eta_s >= 60 else f" ETA {eta_s}s"
+
+            if on_progress:
+                on_progress(0, total_tbl, f"loading columns {cs}/{total_tbl}{eta}")
+
+            bind_list = ','.join([f":t{i}" for i in range(len(chunk))])
+            bind_params = {"schema": schema_upper}
+            for i, tn in enumerate(chunk):
+                bind_params[f"t{i}"] = tn
+
+            cur.execute(f"""
+                SELECT c.TABLE_NAME, c.COLUMN_NAME, c.DATA_TYPE,
+                       CASE WHEN c.DATA_TYPE IN ('VARCHAR2','CHAR','NVARCHAR2') THEN c.DATA_TYPE || '(' || c.DATA_LENGTH || ')'
+                            WHEN c.DATA_TYPE = 'NUMBER' AND c.DATA_PRECISION IS NOT NULL THEN c.DATA_TYPE || '(' || c.DATA_PRECISION || CASE WHEN c.DATA_SCALE > 0 THEN ',' || c.DATA_SCALE ELSE '' END || ')'
+                            ELSE c.DATA_TYPE END AS FULL_TYPE,
+                       c.NULLABLE, c.DATA_DEFAULT, c.COLUMN_ID,
+                       c.DATA_LENGTH, c.DATA_PRECISION, c.DATA_SCALE
+                FROM {prefix}_TAB_COLUMNS c
+                WHERE c.OWNER = :schema AND c.TABLE_NAME IN ({bind_list})
+                ORDER BY c.TABLE_NAME, c.COLUMN_ID
+            """, bind_params)
+            for row in cur.fetchall():
+                tname = row[0]
+                if tname not in all_columns:
+                    all_columns[tname] = []
+                all_columns[tname].append({
+                    "name": row[1], "data_type": row[2], "type": row[3],
+                    "nullable": row[4], "default": str(row[5]).strip() if row[5] else None,
+                    "column_id": row[6],
+                    "data_length": row[7], "precision": row[8], "scale": row[9],
+                })
+                col_count += 1
+            chunk_times.append(_time.time() - t0)
+
+        if on_progress:
+            on_progress(0, total_tbl, f"columns done ({col_count})")
+
+        if on_progress:
+            on_progress(0, total_tbl, "loading col comments...")
+
+        # ═══ Pre-load ALL column comments ═══
+        col_comments = {}
+        try:
+            cur.execute(f"""
+                SELECT TABLE_NAME, COLUMN_NAME, COMMENTS FROM {prefix}_COL_COMMENTS
+                WHERE OWNER = :schema AND COMMENTS IS NOT NULL
+                {_pre_clause()}
+            """, {"schema": schema_upper, **_pre_params})
+            for tname, cname, comment in cur.fetchall():
+                col_comments[f"{tname}.{cname}"] = comment
+        except Exception:
+            pass
+
+        if on_progress:
+            on_progress(0, total_tbl, "loading PKs...")
+
+        # ═══ Pre-load ALL primary keys ═══
+        pk_cols = set()
+        try:
+            cur.execute(f"""
+                SELECT acc.TABLE_NAME, acc.COLUMN_NAME
+                FROM {prefix}_CONSTRAINTS ac
+                JOIN {prefix}_CONS_COLUMNS acc ON acc.CONSTRAINT_NAME = ac.CONSTRAINT_NAME AND acc.OWNER = ac.OWNER
+                WHERE ac.OWNER = :schema AND ac.CONSTRAINT_TYPE = 'P'
+                {_pre_clause('ac')}
+            """, {"schema": schema_upper, **_pre_params})
+            for tname, cname in cur.fetchall():
+                pk_cols.add(f"{tname}.{cname}")
+        except Exception:
+            pass
+
+        if on_progress:
+            on_progress(0, total_tbl, "loading constraint columns...")
+
+        # ═══ Pre-load ALL constraint columns (for COLUMNS_LIST aggregation) ═══
+        cons_cols = {}  # {constraint_name: [col1, col2, ...]} ordered
+        try:
+            cur.execute(f"""
+                SELECT CONSTRAINT_NAME, COLUMN_NAME
+                FROM {prefix}_CONS_COLUMNS
+                WHERE OWNER = :schema
+                {_pre_clause()}
+                ORDER BY CONSTRAINT_NAME, POSITION
+            """, {"schema": schema_upper, **_pre_params})
+            for cname, col in cur.fetchall():
+                cons_cols.setdefault(cname, []).append(col)
+        except Exception:
+            pass
+
+        if on_progress:
+            on_progress(0, total_tbl, "loading constraints...")
+
+        # ═══ Pre-load ALL constraints (now includes P/U/R/C and columns_list) ═══
+        all_constraints = {}
+        try:
+            cur.execute(f"""
+                SELECT ac.TABLE_NAME, ac.CONSTRAINT_NAME, ac.CONSTRAINT_TYPE,
+                       ac.SEARCH_CONDITION,
+                       (SELECT TABLE_NAME FROM {prefix}_CONSTRAINTS WHERE CONSTRAINT_NAME = ac.R_CONSTRAINT_NAME AND OWNER = ac.OWNER AND ROWNUM = 1) AS REF_TABLE
+                FROM {prefix}_CONSTRAINTS ac
+                WHERE ac.OWNER = :schema AND ac.CONSTRAINT_TYPE IN ('P','U','R','C')
+                {_pre_clause('ac')}
+                ORDER BY ac.TABLE_NAME, ac.CONSTRAINT_TYPE
+            """, {"schema": schema_upper, **_pre_params})
+            for tname, cname, ctype, search_cond, ref_table in cur.fetchall():
+                if tname not in all_constraints:
+                    all_constraints[tname] = []
+                c = {"name": cname, "type": ctype}
+                cols = cons_cols.get(cname)
+                if cols:
+                    c["columns_list"] = ",".join(cols)
+                if search_cond:
+                    c["condition"] = str(search_cond)
+                if ref_table:
+                    c["ref_table"] = ref_table
+                all_constraints[tname].append(c)
+        except Exception:
+            pass
+
+        if on_progress:
+            on_progress(0, total_tbl, "loading indexes...")
+
+        # ═══ Pre-load ALL indexes + columns ═══
+        idx_cols = {}  # {index_name: [col1, col2, ...]} ordered
+        try:
+            cur.execute(f"""
+                SELECT INDEX_NAME, COLUMN_NAME
+                FROM {prefix}_IND_COLUMNS
+                WHERE INDEX_OWNER = :schema
+                {_pre_clause()}
+                ORDER BY INDEX_NAME, COLUMN_POSITION
+            """, {"schema": schema_upper, **_pre_params})
+            for iname, col in cur.fetchall():
+                idx_cols.setdefault(iname, []).append(col)
+        except Exception:
+            pass
+
+        all_indexes = {}  # {table_name: [{name,type,uniqueness,columns_list,...}, ...]}
+        try:
+            cur.execute(f"""
+                SELECT TABLE_NAME, INDEX_NAME, INDEX_TYPE, UNIQUENESS,
+                       TABLESPACE_NAME, STATUS, PARTITIONED
+                FROM {prefix}_INDEXES
+                WHERE OWNER = :schema
+                  AND INDEX_NAME NOT LIKE 'BIN$%%'
+                {_pre_clause()}
+                ORDER BY TABLE_NAME, INDEX_NAME
+            """, {"schema": schema_upper, **_pre_params})
+            for tname, iname, itype, uniq, ts, status, partitioned in cur.fetchall():
+                if tname not in all_indexes:
+                    all_indexes[tname] = []
+                ix = {"name": iname, "type": itype, "uniqueness": uniq}
+                cols = idx_cols.get(iname)
+                if cols:
+                    ix["columns_list"] = ",".join(cols)
+                if ts:
+                    ix["tablespace"] = ts
+                if status:
+                    ix["status"] = status
+                if partitioned:
+                    ix["partitioned"] = partitioned
+                all_indexes[tname].append(ix)
+        except Exception:
+            pass
+
+        if on_progress:
+            on_progress(0, total_tbl, "building entries...")
+
+        # ═══ Build results per table ═══
+        for idx, (table_name_raw, last_ddl, table_comment, obj_type) in enumerate(tables):
+            table_name = table_name_raw or ''
+            if not table_name:
+                continue
+
+            if on_progress:
+                on_progress(idx + 1, total_tbl, table_name)
+
+            bau_type = obj_type
+
+            # View source (still per-object — small number of views)
+            view_source = None
+            if obj_type == 'VIEW':
+                try:
+                    cur.execute(f"SELECT TEXT FROM {prefix}_VIEWS WHERE OWNER = :schema AND VIEW_NAME = :vname",
+                               {"schema": schema_upper, "vname": table_name})
+                    row = cur.fetchone()
+                    if row and row[0]:
+                        view_source = f"CREATE OR REPLACE VIEW {schema_upper}.{table_name} AS\n{row[0]}"
+                except Exception:
+                    pass
+            elif obj_type == 'MATERIALIZED VIEW':
+                try:
+                    cur.execute(f"SELECT QUERY FROM {prefix}_MVIEWS WHERE OWNER = :schema AND MVIEW_NAME = :vname",
+                               {"schema": schema_upper, "vname": table_name})
+                    row = cur.fetchone()
+                    if row and row[0]:
+                        view_source = f"CREATE MATERIALIZED VIEW {schema_upper}.{table_name} AS\n{row[0]}"
+                except Exception:
+                    pass
+
+            # Columns from pre-loaded dict
+            columns = []
+            for c in all_columns.get(table_name, []):
+                col = {"name": c["name"], "type": c["type"], "nullable": c["nullable"]}
+                if c.get("column_id") is not None:
+                    col["column_id"] = c["column_id"]
+                if f"{table_name}.{c['name']}" in pk_cols:
+                    col["is_pk"] = "Y"
+                if c["default"]:
+                    col["default"] = c["default"]
+                comment = col_comments.get(f"{table_name}.{c['name']}")
+                if comment:
+                    col["comment"] = comment
+                # UI inference (server-side) needs raw size metadata
+                if c.get("data_length") is not None:
+                    col["data_length"] = c["data_length"]
+                if c.get("precision") is not None:
+                    col["precision"] = c["precision"]
+                if c.get("scale") is not None:
+                    col["scale"] = c["scale"]
+                columns.append(col)
+
+            constraints = all_constraints.get(table_name, [])
+            indexes = all_indexes.get(table_name, [])
+
+            entry = {
+                "name": table_name,
+                "type": bau_type,
+                "last_ddl": last_ddl,
+                "columns": columns,
+            }
+            if table_comment:
+                entry["comment"] = table_comment
+            if constraints:
+                entry["constraints"] = constraints
+            if indexes:
+                entry["indexes"] = indexes
+            if view_source:
+                entry["source"] = view_source
+            result.append(entry)
+
+        cur.close()
+        return result
+
+    # ─────────────────────────────────────────────────────────
+    # APEX extractor (DOCAPEX module)
+    # ─────────────────────────────────────────────────────────
+    def extract_apex(self, schema: str, application_id: int, on_progress=None) -> dict:
+        """Snapshot one Oracle APEX application from the APEX_* dictionary views.
+
+        Returns a dict matching the shape consumed by SYNC_APEX_APP on the server:
+            {
+              "schema": <upper schema>,
+              "app":     { application_id, app_name, app_alias, ... },
+              "pages":   [ {page_id, page_name, ...}, ... ],
+              "regions": [ {page_id, region_id, ...}, ... ],
+              "items":   [ {page_id, region_id, item_id, ...}, ... ],
+              "proc":    [ {page_id, process_id, ...}, ... ],
+              "da":      [ {page_id, region_id, da_id, ...}, ... ]
+            }
+
+        The agent must have SELECT on APEX_APPLICATIONS and the APEX_APPLICATION_PAGE_*
+        views (granted to PUBLIC by default in standard APEX installs).
+        """
+        self._set_action(f"EXTRACT_APEX:{schema}:{application_id}")
+        schema_upper = schema.upper()
+        cur = self._conn.cursor()
+
+        def _fmt_date(v):
+            return v.strftime("%Y-%m-%dT%H:%M:%S") if v else None
+
+        def _to_clob(v):
+            # oracledb returns LobVar for CLOB columns — call .read() to get str.
+            if v is None:
+                return None
+            if hasattr(v, "read"):
+                try:
+                    return v.read()
+                except Exception:
+                    return None
+            return str(v)
+
+        # --- APP --------------------------------------------------------
+        if on_progress: on_progress(1, 6, "fetching app")
+        cur.execute("""
+            SELECT APPLICATION_ID, APPLICATION_NAME, ALIAS, WORKSPACE,
+                   AUTHENTICATION_SCHEME, THEME_NAME, BUILD_STATUS, VERSION,
+                   PAGE_COUNT, LAST_UPDATED_BY, LAST_UPDATED_ON, OWNER
+              FROM APEX_APPLICATIONS
+             WHERE APPLICATION_ID = :app_id
+               AND OWNER = :owner
+        """, app_id=application_id, owner=schema_upper)
+        row = cur.fetchone()
+        if not row:
+            cur.close()
+            raise ValueError(
+                f"APEX application {application_id} not found for owner {schema_upper}.")
+        app = {
+            "application_id":        row[0],
+            "app_name":              row[1],
+            "app_alias":             row[2],
+            "workspace_name":        row[3],
+            "authentication_scheme": row[4],
+            "theme_name":            row[5],
+            "build_status":          row[6],
+            "app_version":           row[7],
+            "page_count":            row[8],
+            "last_updated_by":       row[9],
+            "last_updated_on":       _fmt_date(row[10]),
+        }
+
+        # --- PAGES ------------------------------------------------------
+        if on_progress: on_progress(2, 6, "fetching pages")
+        cur.execute("""
+            SELECT PAGE_ID, PAGE_NAME, PAGE_TITLE, PAGE_ALIAS, PAGE_MODE,
+                   PAGE_GROUP, PARENT_PAGE_ID, AUTHORIZATION_SCHEME, HELP_TEXT
+              FROM APEX_APPLICATION_PAGES
+             WHERE APPLICATION_ID = :app_id
+             ORDER BY PAGE_ID
+        """, app_id=application_id)
+        pages = []
+        for r in cur.fetchall():
+            pages.append({
+                "page_id":              r[0],
+                "page_name":            r[1],
+                "page_title":           r[2],
+                "page_alias":           r[3],
+                "page_mode":            r[4],
+                "page_type":            r[5],   # PAGE_GROUP serves as page_type label
+                "parent_page_id":       r[6],
+                "authorization_scheme": r[7],
+                "help_text":            _to_clob(r[8]),
+            })
+
+        # --- REGIONS ----------------------------------------------------
+        if on_progress: on_progress(3, 6, "fetching regions")
+        cur.execute("""
+            SELECT PAGE_ID, REGION_ID, REGION_NAME, REGION_SOURCE_TYPE, TEMPLATE_NAME,
+                   DISPLAY_POINT, DISPLAY_SEQUENCE, PARENT_REGION_ID, REGION_SOURCE
+              FROM APEX_APPLICATION_PAGE_REGIONS
+             WHERE APPLICATION_ID = :app_id
+             ORDER BY PAGE_ID, DISPLAY_SEQUENCE, REGION_ID
+        """, app_id=application_id)
+        regions = []
+        for r in cur.fetchall():
+            regions.append({
+                "page_id":          r[0],
+                "region_id":        r[1],
+                "region_name":      r[2],
+                "region_type":      r[3],
+                "region_template":  r[4],
+                "display_position": r[5],
+                "display_sequence": r[6],
+                "parent_region_id": r[7],
+                "region_source":    _to_clob(r[8]),
+            })
+
+        # --- ITEMS ------------------------------------------------------
+        if on_progress: on_progress(4, 6, "fetching items")
+        cur.execute("""
+            SELECT PAGE_ID, REGION_ID, ITEM_ID, ITEM_NAME, DISPLAY_AS,
+                   LABEL, DISPLAY_SEQUENCE, NULL AS DATA_TYPE,
+                   IS_REQUIRED, ITEM_DEFAULT, ITEM_SOURCE_TYPE, ITEM_SOURCE,
+                   LOV_NAMED_LOV, HELP_TEXT
+              FROM APEX_APPLICATION_PAGE_ITEMS
+             WHERE APPLICATION_ID = :app_id
+             ORDER BY PAGE_ID, DISPLAY_SEQUENCE, ITEM_NAME
+        """, app_id=application_id)
+        items = []
+        for r in cur.fetchall():
+            items.append({
+                "page_id":          r[0],
+                "region_id":        r[1],
+                "item_id":          r[2],
+                "item_name":        r[3],
+                "item_type":        r[4],
+                "label":            r[5],
+                "display_sequence": r[6],
+                "data_type":        r[7],
+                "is_required":      ("Y" if r[8] in ("Yes", "Y", True) else "N"),
+                "default_value":    r[9],
+                "source_type":      r[10],
+                "source_value":     r[11],
+                "lov_name":         r[12],
+                "help_text":        _to_clob(r[13]),
+            })
+
+        # --- PROC -------------------------------------------------------
+        if on_progress: on_progress(5, 6, "fetching processes")
+        cur.execute("""
+            SELECT PAGE_ID, PROCESS_ID, PROCESS_NAME, PROCESS_TYPE,
+                   PROCESS_POINT, EXECUTION_SEQUENCE,
+                   PROCESS_SOURCE, WHEN_BUTTON_LABEL
+              FROM APEX_APPLICATION_PAGE_PROC
+             WHERE APPLICATION_ID = :app_id
+             ORDER BY PAGE_ID, EXECUTION_SEQUENCE, PROCESS_ID
+        """, app_id=application_id)
+        proc = []
+        for r in cur.fetchall():
+            proc.append({
+                "page_id":             r[0],
+                "process_id":          r[1],
+                "process_name":        r[2],
+                "process_type":        r[3],
+                "process_point":       r[4],
+                "display_sequence":    r[5],
+                "process_source":      _to_clob(r[6]),
+                "when_button_pressed": r[7],
+            })
+
+        # --- DA ---------------------------------------------------------
+        if on_progress: on_progress(6, 6, "fetching dynamic actions")
+        cur.execute("""
+            SELECT PAGE_ID, NULL AS REGION_ID, DYNAMIC_ACTION_ID, DYNAMIC_ACTION_NAME,
+                   EVENT_NAME, AFFECTED_ELEMENTS_TYPE, AFFECTED_ELEMENTS,
+                   CONDITION_CLIENT_SIDE_TYPE, CONDITION_CLIENT_SIDE_EXPR1
+              FROM APEX_APPLICATION_PAGE_DA
+             WHERE APPLICATION_ID = :app_id
+             ORDER BY PAGE_ID, DYNAMIC_ACTION_ID
+        """, app_id=application_id)
+        da = []
+        for r in cur.fetchall():
+            da.append({
+                "page_id":         r[0],
+                "region_id":       r[1],
+                "da_id":           r[2],
+                "da_name":         r[3],
+                "event_name":      r[4],
+                "selection_type":  r[5],
+                "selection_value": r[6],
+                "condition_type":  r[7],
+                "condition_value": r[8],
+                "actions_json":    None,  # v1: aggregate APEX_APPLICATION_PAGE_DA_ACTS later
+            })
+
+        cur.close()
+        return {
+            "schema":  schema_upper,
+            "app":     app,
+            "pages":   pages,
+            "regions": regions,
+            "items":   items,
+            "proc":    proc,
+            "da":      da,
+        }
+