pythia-plsql 0.8.0__tar.gz → 0.9.0__tar.gz

{pythia_plsql-0.8.0/scripts/pythia_plsql.egg-info → pythia_plsql-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.8.0
+Version: 0.9.0
 Summary: PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback.
 License: MIT
 Project-URL: Homepage, https://github.com/thaildhe172591/pythia
@@ -211,7 +211,7 @@ Per-group write policy, `.pythia/policy.json` (defaults shown):
 | Group | Default | Is rollback real? |
 |---|---|---|
 | `plsql_source` | `confirm` | **Yes — completely.** Source is recoverable from `ALL_SOURCE`. |
-| `data_dml` | `deny` | **No.** After commit only Flashback Query remains, within undo retention. |
+| `data_dml` | `deny` | **No.** After commit only Flashback Query remains, within undo retention. Revalidation checks the row set *before* the write; it is not an undo. |
 | `structural` | `deny` | **Almost never.** `DROP COLUMN` is permanent; a dropped table may be in the Recycle Bin. |
 | `grants` | `deny` | Yes, but by hand. |
 | `session` | `allow` | Not needed. |

{pythia_plsql-0.8.0 → pythia_plsql-0.9.0}/README.md

@@ -197,7 +197,7 @@ Per-group write policy, `.pythia/policy.json` (defaults shown):
 | Group | Default | Is rollback real? |
 |---|---|---|
 | `plsql_source` | `confirm` | **Yes — completely.** Source is recoverable from `ALL_SOURCE`. |
-| `data_dml` | `deny` | **No.** After commit only Flashback Query remains, within undo retention. |
+| `data_dml` | `deny` | **No.** After commit only Flashback Query remains, within undo retention. Revalidation checks the row set *before* the write; it is not an undo. |
 | `structural` | `deny` | **Almost never.** `DROP COLUMN` is permanent; a dropped table may be in the Recycle Bin. |
 | `grants` | `deny` | Yes, but by hand. |
 | `session` | `allow` | Not needed. |

{pythia_plsql-0.8.0 → pythia_plsql-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythia-plsql"
-version = "0.8.0"
+version = "0.9.0"
 description = "PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback."
 readme = "README.md"
 license = { text = "MIT" }

{pythia_plsql-0.8.0 → pythia_plsql-0.9.0}/scripts/pythia.py

@@ -798,6 +798,165 @@ def prepare_statement(sql, group):
     return text
 
 
+REVALIDATE_REFUSAL = """\
+Refused: pythia cannot work out which rows this statement would touch, because
+%s.
+A data_dml write is approved on the rows it affects, so a row set that cannot
+be measured is refused rather than guessed at.
+Rewrite it as one UPDATE or DELETE over one table with one WHERE."""
+
+
+def mask_literals(sql):
+    """A same-length copy with quoted text and comments blanked to spaces.
+    Length is the contract: an index found in the mask points at the same
+    character in the original, which is what lets dml_probe trust a keyword
+    scan without carrying a real parser."""
+    out, i, n = [], 0, len(sql)
+    while i < n:
+        if sql[i] == "'":
+            out.append(" ")
+            i += 1
+            while i < n:                    # a doubled '' simply closes and
+                out.append(" ")             # reopens — blanked either way
+                i += 1
+                if sql[i - 1] == "'":
+                    break
+        elif sql.startswith("--", i):
+            while i < n and sql[i] != "\n":
+                out.append(" ")
+                i += 1
+        elif sql.startswith("/*", i):
+            end = sql.find("*/", i + 2)
+            end = n if end < 0 else end + 2
+            out.append(" " * (end - i))
+            i = end
+        else:
+            out.append(sql[i])
+            i += 1
+    return "".join(out)
+
+
+def dml_probe(stmt):
+    """(verb, target, predicate|None): the SELECT-able description of the rows
+    an UPDATE or DELETE will touch. None for INSERT — nothing exists
+    beforehand, so there is nothing to revalidate. Everything else is refused,
+    for classify()'s reason: a parser that guesses generously is a parser that
+    lets deny be bypassed.
+
+    target is a span of text, not a parsed identifier, so a schema qualifier
+    and an alias survive and a predicate written against the alias resolves."""
+    s = skip_leading_noise(stmt)
+    m = re.match(r"(insert|update|delete|merge)\b", s, re.I)
+    verb = m.group(1).lower() if m else ""
+    if verb == "insert":
+        return None
+    if verb == "merge":
+        sys.exit("Refused: a MERGE cannot be revalidated — the rows it touches "
+                 "are decided by a join against its source query, so pythia "
+                 "cannot show you the set you would be approving.\n"
+                 "Express it as an UPDATE and/or a DELETE, or run it by hand "
+                 "with a DBA watching.")
+    if re.search(r"q'", s, re.I):
+        sys.exit(REVALIDATE_REFUSAL % "it uses an alternative-quoted (q'...') "
+                                      "literal, which this parser does not read")
+    masked = mask_literals(s)
+    if re.search(r"\bselect\b", masked, re.I):
+        sys.exit(REVALIDATE_REFUSAL % "it contains a subquery, so its row set "
+                                      "is not one predicate over one table")
+    wheres = [w.start() for w in re.finditer(r"\bwhere\b", masked, re.I)]
+    if len(wheres) > 1:
+        sys.exit(REVALIDATE_REFUSAL % "it has more than one WHERE, so which "
+                                      "one selects the rows would be a guess")
+    head = re.match(r"delete\s+(?:from\s+)?" if verb == "delete"
+                    else r"update\s+", masked, re.I)
+    start = head.end()
+    if verb == "update":
+        sets = re.search(r"\bset\b", masked[start:], re.I)
+        if not sets:
+            sys.exit(REVALIDATE_REFUSAL % "the UPDATE has no SET clause")
+        end = start + sets.start()
+    else:
+        end = wheres[0] if wheres else len(masked)
+    if wheres and wheres[0] < end:
+        sys.exit(REVALIDATE_REFUSAL % "its WHERE comes before the table it "
+                                      "reads, which this parser does not expect")
+    target = s[start:end].strip()
+    if not target:
+        sys.exit(REVALIDATE_REFUSAL % "no table name follows the verb")
+    pred = s[wheres[0] + 5:].strip() if wheres else None
+    return verb, target, pred
+
+
+def count_sql(target, pred):
+    """The fingerprint query. Interpolated, not bound: a table name and a
+    predicate are not bindable. The text comes from the very file whose DML is
+    about to run, so this opens no trust boundary that statement does not open
+    already — but it runs BEFORE approval, which SECURITY.md says out loud."""
+    return ("select count(*) n, sum(ora_hash(rowidtochar(rowid))) s, "
+            "min(ora_hash(rowidtochar(rowid))) lo, "
+            "max(ora_hash(rowidtochar(rowid))) hi from "
+            + target + (f" where {pred}" if pred else ""))
+
+
+def sample_sql(target, pred):
+    return ("select * from " + target + (f" where {pred}" if pred else "")
+            + " fetch first :n rows only")
+
+
+def measure_row_set(conn, target, pred, limit=10):
+    """Count, fingerprint and sample the rows the statement will touch.
+    Failing to measure is a refusal, never a reason to proceed: a write
+    approved on a row set nobody could see is what this exists to prevent.
+
+    ponytail: ROWID tracks set membership, not row contents — an in-place
+    update to an approved row keeps its ROWID. Hash the sampled columns too if
+    content drift ever needs catching."""
+    try:
+        _, agg = run_query(conn, count_sql(target, pred))
+        cols, rows = run_query(conn, sample_sql(target, pred),
+                               {"n": fetch_n(limit)})
+    except Exception as e:            # the driver's exception class is imported
+        sys.exit("Refused: pythia could not measure the rows this "  # in main()
+                 f"statement would touch.\n  {target} — {e}\n"
+                 "Revalidation is mandatory for UPDATE and DELETE, so a set "
+                 "that cannot be measured cannot be approved.")
+    n, s, lo, hi = (list(agg[0]) + [None] * 4)[:4] if agg else (0, 0, 0, 0)
+    return {"target": target, "predicate": pred or "", "count": int(n or 0),
+            "hash": f"{s or 0}/{lo or 0}/{hi or 0}",
+            "columns": list(cols),
+            "sample": [[cell(v) for v in r] for r in rows[:limit]],
+            "truncated": len(rows) > limit}
+
+
+def fingerprint_text(row_set):
+    """What the token hashes. Empty when there is no row set, so plsql_source
+    tokens stay byte-identical to the ones 0.8.0 printed."""
+    if not row_set:
+        return ""
+    return f"rows={row_set['count']} hash={row_set['hash']}"
+
+
+def render_row_set(row_set, en=False, indent="  "):
+    """The rows an approval is about — printed identically by the preview and
+    by approve, because what is approved must be what was shown."""
+    n = row_set["count"]
+    where = f" where {row_set['predicate']}" if row_set["predicate"] else ""
+    out = [f"{indent}{paint(str(n) + ' rows', 'bold', en)} in "
+           f"{row_set['target']}{where}"]
+    if n > 1000:
+        out.append(indent + paint("! more rows than anyone can read one by "
+                                  "one — the count and the fingerprint are "
+                                  "the whole of what you are approving",
+                                  "yellow", en))
+    if row_set["sample"]:
+        out.append(indent + "\t".join(row_set["columns"]))
+        out.extend(indent + "\t".join(r) for r in row_set["sample"])
+        if row_set["truncated"]:
+            out.append(f"{indent}-- truncated at {len(row_set['sample'])} of "
+                       f"{n} rows")
+    return out
+
+
 POLICY_DEFAULTS = {"plsql_source": "confirm", "data_dml": "deny",
                    "structural": "deny", "grants": "deny", "session": "allow"}
 
@@ -805,6 +964,7 @@ ROLLBACK_TABLE = """\
 Is rollback real?  (this table also appears in README.md and pythia-apply)
   plsql_source  Yes - completely. Source is recoverable from ALL_SOURCE.
   data_dml      No. After commit only Flashback Query remains, within undo retention.
+                Revalidation checks the row set before the write; it is not an undo.
   structural    Almost never. DROP COLUMN is permanent; a dropped table may be in the Recycle Bin.
   grants        Yes, but by hand.
   session       Not needed."""
@@ -969,9 +1129,11 @@ def grant_path(root, token):
     return grants_root(root) / f"{token}.json"
 
 
-def mint_grant(root, token, conn_name, now=None):
+def mint_grant(root, token, conn_name, now=None, revalidate=None):
     """Record one developer approval. Single use, short-lived, bound to the
-    connection the preview ran on."""
+    connection the preview ran on. `revalidate` is the row-set fingerprint the
+    human was shown — audit data, not a second gate: the enforcement is the
+    token, which already hashes that same fingerprint."""
     import datetime
     now = now or datetime.datetime.now()
     rec = {"token": token,
@@ -980,8 +1142,7 @@ def mint_grant(root, token, conn_name, now=None):
            "expires_at": (now + datetime.timedelta(
                minutes=GRANT_TTL_MINUTES)).isoformat(timespec="seconds"),
            "used_at": None,
-           # reserved: the data_dml spec re-checks the affected row set here
-           "revalidate": None}
+           "revalidate": revalidate or None}
     d = grants_root(root)
     d.mkdir(parents=True, exist_ok=True)
     grant_path(root, token).write_text(json.dumps(rec, indent=2) + "\n",
@@ -1798,7 +1959,13 @@ def run_apply(conn, schema, ns, file_text, origin=None):
         extra = ("no snapshot can undo it after commit"
                  if group in ("data_dml", "structural", "grants")
                  else "policy forbids it")
-        sys.exit(f"Refused: {group} is set to deny — {extra}.\n"
+        note = ("\nRevalidation narrows that risk without removing it: the "
+                "preview shows the rows and the count, apply refuses if that "
+                "set moved, and the write is rolled back if the statement "
+                "touches a different number of rows. What nothing here can do "
+                "is undo a committed DELETE."
+                if group == "data_dml" else "")
+        sys.exit(f"Refused: {group} is set to deny — {extra}.{note}\n"
                  f"To allow it once you have weighed that: "
                  f"{invocation()} policy set {group} confirm")
     stmt = prepare_statement(file_text, group)
@@ -1837,17 +2004,23 @@ def run_apply(conn, schema, ns, file_text, origin=None):
 
     # 1. SNAPSHOT — before anything else, unconditionally.
     db_source = ""
+    row_set = None
     if group == "plsql_source":
         _, rows = run_query(conn, load_query("object-source.sql"),
                             {"s": schema, "n": name, "t": otype})
         db_source = "".join(cell(r[0]) for r in rows)
-    token = apply_token(otype, name, file_text, db_source)
+    elif group == "data_dml":
+        # the row set IS the snapshot here: nothing can undo a committed DML,
+        # so what the developer approves is the set, and the token carries it
+        probe = dml_probe(stmt)
+        if probe:
+            row_set = measure_row_set(conn, probe[1], probe[2])
+    token = apply_token(otype, name, file_text,
+                        db_source + fingerprint_text(row_set))
     if ns.yes and not human_at_the_keyboard():
         sys.exit(HEADLESS_YES_MSG)
     if ns.confirm and ns.confirm != token:
-        sys.exit("The confirmation token does not match: the file or the "
-                 "database object changed since that preview. Preview again:\n"
-                 f"  {invocation()} apply {ns.file}")
+        sys.exit(token_mismatch_message(ns, row_set))
     # The token proves the content did not move; the grant proves a human
     # approved it. --yes is itself that human act, at a real console.
     grant = None
@@ -1865,12 +2038,16 @@ def run_apply(conn, schema, ns, file_text, origin=None):
             "token": token, "applied": False,
             "confirmed_via": ("yes" if ns.yes else
                               "grant" if confirmed else "preview"),
+            "row_set": row_set,
             "grant_minted_at": (grant or {}).get("minted_at"),
             "tty": human_at_the_keyboard(),
             "invalid_before": invalid_before, **(origin or {})}
     entry = write_journal_entry(ns.project_root, otype, name, db_source,
                                 file_text, meta)
-    created = not db_source.strip()
+    # "created" is about an OBJECT that did not exist. A DML/DDL statement has
+    # no object identity, so it is never "new" — and saying so would promise a
+    # DROP-shaped undo that does not exist for those groups.
+    created = not db_source.strip() and group == "plsql_source"
 
     # 2. IMPACT
     summary = ""
@@ -1891,19 +2068,31 @@ def run_apply(conn, schema, ns, file_text, origin=None):
         print(json.dumps({"ok": True, "object": name, "type": otype,
                           "created": created, "changed_lines": changed,
                           "summary": summary, "warning": warn,
+                          "row_set": row_set,
                           "naming_warning": style, "token": token,
                           "journal": entry, "will_apply": confirmed}))
     else:
         en = getattr(ns, "color", False)
-        if created:
-            head = "new object"
-        elif changed == 0:
-            head = "no source change (recompile)"
+        if group != "plsql_source":
+            print(f"\n  {paint(group, 'bold', en)} statement on {schema}")
         else:
-            head = f"{changed} lines changed"
-        print(f"\n  {paint(f'{name} ({otype})', 'bold', en)} in {schema} — {head}")
+            if created:
+                head = "new object"
+            elif changed == 0:
+                head = "no source change (recompile)"
+            else:
+                head = f"{changed} lines changed"
+            print(f"\n  {paint(f'{name} ({otype})', 'bold', en)} in {schema} "
+                  f"— {head}")
         if summary:
             print(f"  {summary.lstrip('- ')}")
+        if row_set is not None:
+            print()
+            for ln in render_row_set(row_set, en):
+                print(ln)
+        elif group == "data_dml":
+            print("\n  INSERT — no rows exist beforehand, so there is no row "
+                  "set to revalidate.")
         if warn:
             print(f"\n  {paint(warn, 'yellow', en)}")
         if style:
@@ -1914,7 +2103,9 @@ def run_apply(conn, schema, ns, file_text, origin=None):
                 print(f"  {paint_diff_line(ln, en)}")
         print(paint(f"\n  Snapshot saved: {journal_root(ns.project_root) / entry}",
                     "dim", en))
-        if not confirmed:
+        if not confirmed and group == "plsql_source":
+            # only this group has a restore.sql worth running: the others get a
+            # generated DROP that nothing would accept
             print(paint("  Rollback file for the current database version — "
                         "use it if this is\n  run by hand instead: "
                         f"{journal_root(ns.project_root) / entry / 'restore.sql'}",
@@ -1940,6 +2131,17 @@ def run_apply(conn, schema, ns, file_text, origin=None):
                         "'IDENTIFIERS:ALL, STATEMENTS:ALL'")
     with conn.cursor() as cur:
         cur.execute(stmt)
+        affected = cur.rowcount if group == "data_dml" else None
+    if group == "data_dml":
+        # the last-millisecond check: the probe ran before this statement, and
+        # READ COMMITTED lets the world move in between
+        if row_set is not None and affected != row_set["count"]:
+            conn.rollback()
+            sys.exit(f"Rolled back: the statement touched {affected} rows, but "
+                     f"{row_set['count']} were approved.\nNothing was "
+                     "committed — the rows moved between the check and the "
+                     "write. Preview again.")
+        conn.commit()          # DDL commits itself; DML never did until now
     if grant is not None:
         spend_grant(ns.project_root, token)   # one approval, one write
 
@@ -1968,14 +2170,20 @@ def run_apply(conn, schema, ns, file_text, origin=None):
         print(json.dumps({"ok": ok, "applied": True, "object": name,
                           "type": otype, "errors": [list(r) for r in own_errors],
                           "newly_invalid": [list(x) for x in broke],
-                          "restore": f"{invocation()} journal restore {entry}",
+                          "rows": affected,
+                          "restore": (f"{invocation()} journal restore {entry}"
+                                      if group == "plsql_source" else None),
+                          "no_undo": group != "plsql_source",
                           "restore_is_drop": created,
                           "restore_blocked_by_policy": (
                               created and undo_group_action(ns) == "deny"),
                           "exit": 0 if ok else 3}))
     else:
         en = getattr(ns, "color", False)
-        if ok:
+        if ok and group == "data_dml":
+            print(paint(f"\n  Applied — {affected} rows changed and "
+                        "committed.", "green", en))
+        elif ok:
             print(paint(f"\n  Applied {name} ({otype}).", "green", en))
             print(paint("  Compiled clean. No new INVALID objects.", "green", en))
         else:
@@ -1992,21 +2200,28 @@ def run_apply(conn, schema, ns, file_text, origin=None):
                 print(f"  {len(broke)} objects were VALID before and are INVALID now:")
                 for n2, t2 in broke:
                     print(paint(f"    {n2} ({t2})", "red", en))
-        if created:
-            print("\n  To undo — note: undo means DROPPING it "
-                  "(it did not exist before):")
+        if group != "plsql_source":
+            # no snapshot was taken, so there is nothing to restore — say that
+            # instead of printing a restore command that would be refused
+            print(paint("\n  There is no undo: the journal kept the statement "
+                        "that ran, not a way back.", "yellow", en))
         else:
-            print("\n  To undo:")
-        print("    " + paint(f"{invocation()} journal restore {entry}",
-                             "cyan", en))
-        if created and undo_group_action(ns) == "deny":
-            # the honest half: that restore is a DROP, DROP is structural,
-            # and structural is deny — so the line above would be refused
-            print(paint("  ...but that restore is a DROP, and structural is "
-                        "set to deny, so it will be refused.", "yellow", en))
-            print(paint("  The developer decides: "
-                        f"{invocation()} policy set structural confirm",
-                        "yellow", en))
+            if created:
+                print("\n  To undo — note: undo means DROPPING it "
+                      "(it did not exist before):")
+            else:
+                print("\n  To undo:")
+            print("    " + paint(f"{invocation()} journal restore {entry}",
+                                 "cyan", en))
+            if created and undo_group_action(ns) == "deny":
+                # the honest half: that restore is a DROP, DROP is structural,
+                # and structural is deny — so the line above would be refused
+                print(paint("  ...but that restore is a DROP, and structural "
+                            "is set to deny, so it will be refused.",
+                            "yellow", en))
+                print(paint("  The developer decides: "
+                            f"{invocation()} policy set structural confirm",
+                            "yellow", en))
     return 0 if ok else 3
 
 
@@ -2033,6 +2248,32 @@ def find_preview_by_token(root, token):
     return None, None
 
 
+def token_mismatch_message(ns, row_set):
+    """Why the token no longer matches. For DML the interesting answer is
+    almost always the rows, and the preview's own journal entry still holds
+    what they were — so say which, instead of a generic 'something moved'."""
+    base = ("The confirmation token does not match: the file or the "
+            "database object changed since that preview. Preview again:\n"
+            f"  {invocation()} apply {ns.file}")
+    if not row_set:
+        return base
+    _, meta = find_preview_by_token(ns.project_root,
+                                    str(ns.confirm).strip().lower())
+    then = (meta or {}).get("row_set") or {}
+    if not then or fingerprint_text(then) == fingerprint_text(row_set):
+        return base                       # the file moved, not the rows
+    if then["count"] != row_set["count"]:
+        moved = (f"{then['count']} rows when you approved it, "
+                 f"{row_set['count']} now")
+    else:
+        moved = (f"still {row_set['count']} rows, but not the same ones — the "
+                 "row fingerprint changed")
+    return ("Refused: the row set moved — " + moved + ".\n"
+            "Nothing was written. The approval covered the rows as they were.\n"
+            "Preview again to see them as they are now:\n"
+            f"  {invocation()} apply {ns.file}")
+
+
 def cmd_approve(conn, schema, ns):
     """The developer's half of the gate: one human act, at a real console,
     that lets the agent's next `apply --confirm` through. Touches no
@@ -2052,12 +2293,15 @@ def cmd_approve(conn, schema, ns):
                  f"  {invocation()} apply <file>")
     conn_name = meta.get("connection") or ""
     prune_expired_grants(ns.project_root)
-    rec = mint_grant(ns.project_root, token, conn_name)
+    row_set = meta.get("row_set")
+    rec = mint_grant(ns.project_root, token, conn_name,
+                     revalidate=fingerprint_text(row_set))
     obj, otype = meta.get("object", "?"), meta.get("type", "?")
     group = meta.get("group", "")
     if ns.json:
         print(json.dumps({"ok": True, "token": token, "conn": conn_name,
                           "object": obj, "type": otype, "group": group,
+                          "rows": (row_set or {}).get("count"),
                           "entry": entry, "minted_at": rec["minted_at"],
                           "expires_at": rec["expires_at"],
                           "ttl_minutes": GRANT_TTL_MINUTES}))
@@ -2071,6 +2315,12 @@ def cmd_approve(conn, schema, ns):
         print(f"  Approving a {group} statement on {meta.get('schema', '?')}:")
         for ln in stmt.splitlines():
             print(f"    {ln}")
+        if row_set:
+            # the rows themselves, exactly as the preview showed them: what is
+            # approved has to be what was seen
+            print()
+            for ln in render_row_set(row_set, en, indent="    "):
+                print(ln)
         print(paint("\n  There is no snapshot for this group — after commit "
                     "it cannot be undone from the journal.", "yellow", en))
     else:
@@ -2090,6 +2340,18 @@ def run_restore(conn, schema, ns):
     """Restore is itself a write: feed the saved statement back through the
     same six steps. There is no second write path and no silent restore."""
     e = read_journal_entry(ns.project_root, ns.id)
+    group = e["meta"].get("group", "plsql_source")
+    if group != "plsql_source":
+        # render_restore() writes a DROP for every group that has no snapshot,
+        # which classifies as structural and dies with a message about the
+        # wrong thing. Say what is actually true, once, for all of them.
+        tail = ("Flashback Query within undo retention is the only route left, "
+                "and it is a DBA's job."
+                if group == "data_dml" else
+                "Reversing it means writing the opposite statement by hand.")
+        sys.exit(f"Refused: entry {ns.id} is a {group} statement, and the "
+                 "journal holds no undo for it — only the statement that "
+                 f"ran.\n{tail}")
     print(f"Restoring from {ns.id} — this is itself a write and goes through "
           "the full six steps.", file=sys.stderr)
     return run_apply(conn, schema, ns, e["restore"], origin={"restored_from": ns.id})

{pythia_plsql-0.8.0 → pythia_plsql-0.9.0/scripts/pythia_plsql.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.8.0
+Version: 0.9.0
 Summary: PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback.
 License: MIT
 Project-URL: Homepage, https://github.com/thaildhe172591/pythia
@@ -211,7 +211,7 @@ Per-group write policy, `.pythia/policy.json` (defaults shown):
 | Group | Default | Is rollback real? |
 |---|---|---|
 | `plsql_source` | `confirm` | **Yes — completely.** Source is recoverable from `ALL_SOURCE`. |
-| `data_dml` | `deny` | **No.** After commit only Flashback Query remains, within undo retention. |
+| `data_dml` | `deny` | **No.** After commit only Flashback Query remains, within undo retention. Revalidation checks the row set *before* the write; it is not an undo. |
 | `structural` | `deny` | **Almost never.** `DROP COLUMN` is permanent; a dropped table may be in the Recycle Bin. |
 | `grants` | `deny` | Yes, but by hand. |
 | `session` | `allow` | Not needed. |

{pythia_plsql-0.8.0 → pythia_plsql-0.9.0}/skills/pythia-apply/SKILL.md

@@ -9,9 +9,9 @@ description: Use when a PL/SQL change is ready to reach the database - applying
 
 **Phase:** Ask → Do — the preview is relayed and approved before the one write door opens
 
-DDL in Oracle commits itself. There is no transaction to roll back — the
-snapshot pythia takes before writing is the only undo there is, and this skill
-exists so that net is always used, and used honestly.
+DDL in Oracle commits itself, so the snapshot pythia takes before writing is
+the only undo there is — and for DML not even that. This skill exists so that
+net is always used, and used honestly.
 
 ## The Iron Law
 
@@ -41,9 +41,8 @@ message.
 Sometimes the developer runs the file themselves — a DBA executes it, a
 release process owns it, or policy denies the group. The preview still ran, so
 a rollback file for the live version exists at
-`.pythia/journal/<entry>/restore.sql`. Never let a change leave your hands for
-manual execution without naming that path alongside the .sql file (`pythia
-history <OBJECT>` lists every captured version).
+`.pythia/journal/<entry>/restore.sql` (`pythia history <OBJECT>` lists every
+captured version). Never let a change leave your hands without naming it.
 
 ## The Workflow
 
@@ -92,10 +91,9 @@ means DROP — policy refuses it under `structural: deny`, and that is correct.
 
 ## Batch mode
 
-`--yes` skips the pause, not the preview — and it is the developer's flag: at
-their terminal it *is* the approval, so no separate approve is needed. A
-frustrated "stop asking" grants it for the task at hand, not from now on:
-confirm the scope once and default to this-batch-only. It never covers restores.
+`--yes` skips the pause, not the preview — it is the developer's flag, and at
+their terminal it *is* the approval. A frustrated "stop asking" grants it for
+the task at hand, not from now on; it never covers restores.
 
 - **Stop at the first exit 3.** Never keep applying onto a broken state.
 - Afterwards report: one line per success, full detail (errors, newly INVALID,
@@ -114,7 +112,7 @@ information for the developer, not an obstacle to route around.
 | Group | Is rollback real? |
 |---|---|
 | `plsql_source` | **Yes — completely.** The source is recoverable from `ALL_SOURCE`. |
-| `data_dml` | **No.** After commit only Flashback Query remains, and only within undo retention. |
+| `data_dml` | **No.** After commit only Flashback Query remains, and only within undo retention. Revalidation checks the row set *before* the write; it is not an undo. |
 | `structural` | **Almost never.** `DROP COLUMN` is permanent; a dropped table may be in the Recycle Bin. |
 | `grants` | Yes, but by hand. |
 | `session` | Not needed. |
@@ -122,6 +120,10 @@ information for the developer, not an obstacle to route around.
 Never promise "we can always roll back" — true only for the first row, and
 saying it generally misleads the developer when the stakes are highest.
 
+`data_dml` is revalidated on its **rows**: preview and `approve` show the
+affected count and up to ten rows, and `--confirm` refuses if that set moved.
+`MERGE`, and anything unmeasurable, is refused rather than guessed at.
+
 ## Red Flags — STOP if you catch yourself thinking
 
 | Thought | Reality |
@@ -133,9 +135,7 @@ saying it generally misleads the developer when the stakes are highest.
 | "apply refused it; run-sql will take it" | The refusal is the product working. Relay it. |
 | "I'll restore quietly to clean up my mistake" | Restores are writes. Same gate, same visibility. |
 | "`$?` said 0 after I piped to tail" | That was tail's 0. Read pythia's own words, or its unpiped code. |
-| "The dev said 'stop asking' once" | That covered that task, not forever. Re-confirm scope on the next one. |
 | "I'll run approve myself to unblock this" | The developer's console act. It refuses you, and routing around it is what this gate exists to stop. |
-| "No approval on file — I'll retry until it works" | Retrying does not create approval. Relay the line, wait for a human. |
 
 ## When NOT to use this skill
 

{pythia_plsql-0.8.0 → pythia_plsql-0.9.0}/tests/test_phase3.py

@@ -70,6 +70,43 @@ def test_prepare_statement_terminators():
         "truncate table a; truncate table b;", "structural"), "one statement")
 
 
+def test_mask_literals_keeps_length_and_blanks_text():
+    m = pythia.mask_literals
+    src = "update t set n = 'x where y' where id = 1"
+    assert len(m(src)) == len(src)
+    assert "where y" not in m(src)
+    assert m("delete from t -- where later" + chr(10)
+             + "where id = 1").count("where") == 1
+    assert m("delete from t /* where */ where id = 1").count("where") == 1
+    assert "it" not in m("update t set n = 'it''s' where id = 1")
+
+
+def test_dml_probe_reads_target_and_predicate():
+    assert pythia.dml_probe("delete from t_order where status = 'DRAFT'") == (
+        "delete", "t_order", "status = 'DRAFT'")
+    assert pythia.dml_probe("delete app.t_order t where t.id = 7") == (
+        "delete", "app.t_order t", "t.id = 7")
+    assert pythia.dml_probe("update t_order t set status = 'X' "
+                            "where t.id = 7") == (
+        "update", "t_order t", "t.id = 7")
+    assert pythia.dml_probe("delete from t_order") == ("delete", "t_order", None)
+    assert pythia.dml_probe("insert into t values (1)") is None
+
+
+def test_dml_probe_refuses_what_it_cannot_measure():
+    expect_exit(lambda: pythia.dml_probe(
+        "merge into t using d on (1=1) when matched then update set x=1"),
+        "merge", "join")
+    expect_exit(lambda: pythia.dml_probe(
+        "delete from t where id in (select id from u)"), "subquery")
+    expect_exit(lambda: pythia.dml_probe(
+        "update t set a = 1 where id in (1) and x = 2 where y = 3"),
+        "more than one where")
+    expect_exit(lambda: pythia.dml_probe(
+        "update t set n = q'{x}' where id = 1"), "quoted")
+    expect_exit(lambda: pythia.dml_probe("update t where id = 1"), "set clause")
+
+
 def test_apply_token_is_content_bound():
     t1 = pythia.apply_token("PACKAGE BODY", "PKG_ORDER", "create...", "old src")
     assert len(t1) == 6 and all(c in "0123456789abcdef" for c in t1)
@@ -135,9 +172,10 @@ def test_newly_invalid_and_diff():
 
 
 class FakeCursor:
-    def __init__(self, script, executed):
+    def __init__(self, script, executed, rowcount=0):
         self.script, self.executed = script, executed
         self.description, self._rows = None, []
+        self.rowcount = rowcount
 
     def execute(self, sql, binds=None):
         self.executed.append((sql, dict(binds or {})))
@@ -166,11 +204,19 @@ class FakeCursor:
 
 
 class FakeConn:
-    def __init__(self, script):
+    def __init__(self, script, rowcount=0):
         self.script, self.executed = script, []
+        self.rowcount = rowcount
+        self.commits, self.rollbacks = 0, 0
 
     def cursor(self):
-        return FakeCursor(self.script, self.executed)
+        return FakeCursor(self.script, self.executed, self.rowcount)
+
+    def commit(self):
+        self.commits += 1
+
+    def rollback(self):
+        self.rollbacks += 1
 
 
 OLD_SRC = "PACKAGE BODY pkg_order AS\n  old line;\nEND;\n"
@@ -214,6 +260,166 @@ def wrote_ddl(conn):
     return [s for s, _ in conn.executed if s.lstrip().lower().startswith("create")]
 
 
+DML_FILE = "delete from t_order where status = 'DRAFT'\n"
+
+
+def dml_script(count=2, hashes=(11, 1, 9), rows=((7, "DRAFT"), (8, "DRAFT"))):
+    s = base_script()
+    s["ora_hash"] = (("N", "S", "LO", "HI"), [(count,) + tuple(hashes)])
+    s["select * from"] = (("ID", "STATUS"), list(rows))
+    return s
+
+
+def dml_ns(root, **kw):
+    ns = apply_ns(root, **kw)
+    ns.file = "d.sql"
+    return ns
+
+
+def allow_dml(root):
+    d = pathlib.Path(root) / ".pythia"
+    d.mkdir(exist_ok=True)
+    (d / "policy.json").write_text(json.dumps({"data_dml": "confirm"}),
+                                   encoding="utf-8")
+
+
+def wrote_dml(conn):
+    return [s for s, _ in conn.executed
+            if s.lstrip().lower().startswith(("delete", "update", "insert"))]
+
+
+def test_dml_preview_measures_the_row_set_and_writes_nothing():
+    with tempfile.TemporaryDirectory() as td:
+        allow_dml(td)
+        conn = FakeConn(dml_script())
+        code = pythia.run_apply(conn, "APP", dml_ns(td), DML_FILE)
+        assert code == 0
+        assert wrote_dml(conn) == [] and conn.commits == 0
+        entry = pythia.list_journal_entries(td)[0]
+        rs = pythia.read_journal_entry(td, entry)["meta"]["row_set"]
+        assert rs["count"] == 2 and rs["target"] == "t_order"
+        assert rs["predicate"] == "status = 'DRAFT'"
+        assert rs["sample"] == [["7", "DRAFT"], ["8", "DRAFT"]]
+
+
+def test_the_row_set_moves_the_token():
+    with tempfile.TemporaryDirectory() as td:
+        allow_dml(td)
+        pythia.run_apply(FakeConn(dml_script(count=2)), "APP",
+                         dml_ns(td), DML_FILE)
+        first = pythia.read_journal_entry(
+            td, pythia.list_journal_entries(td)[0])["meta"]["token"]
+        pythia.run_apply(FakeConn(dml_script(count=3)), "APP",
+                         dml_ns(td), DML_FILE)
+        second = pythia.read_journal_entry(
+            td, pythia.list_journal_entries(td)[0])["meta"]["token"]
+        assert first != second, "the fingerprint must reach the token"
+
+
+def approved(td, conn):
+    """Preview, then approve — the two-step gate, in test form. Returns the
+    token the agent would pass to --confirm."""
+    pythia.run_apply(conn, "APP", dml_ns(td), DML_FILE)
+    entry = pythia.list_journal_entries(td)[0]
+    token = pythia.read_journal_entry(td, entry)["meta"]["token"]
+    pythia.mint_grant(td, token, "DEV")
+    return token
+
+
+def test_dml_commits_once_when_the_rowcount_matches():
+    with tempfile.TemporaryDirectory() as td:
+        allow_dml(td)
+        token = approved(td, FakeConn(dml_script(count=2)))
+        conn = FakeConn(dml_script(count=2), rowcount=2)
+        code = pythia.run_apply(conn, "APP", dml_ns(td, confirm=token), DML_FILE)
+        assert code == 0
+        assert conn.commits == 1 and conn.rollbacks == 0
+        assert wrote_dml(conn)
+
+
+def test_dml_rolls_back_when_the_rowcount_diverges():
+    with tempfile.TemporaryDirectory() as td:
+        allow_dml(td)
+        token = approved(td, FakeConn(dml_script(count=2)))
+        conn = FakeConn(dml_script(count=2), rowcount=5)
+        expect_exit(lambda: pythia.run_apply(
+            conn, "APP", dml_ns(td, confirm=token), DML_FILE),
+            "rolled back", "5", "2")
+        assert conn.rollbacks == 1 and conn.commits == 0
+
+
+def test_a_moved_row_set_refuses_the_confirm():
+    with tempfile.TemporaryDirectory() as td:
+        allow_dml(td)
+        token = approved(td, FakeConn(dml_script(count=2)))
+        conn = FakeConn(dml_script(count=3), rowcount=3)
+        expect_exit(lambda: pythia.run_apply(
+            conn, "APP", dml_ns(td, confirm=token), DML_FILE),
+            "row set moved", "2 rows", "3")
+        assert conn.commits == 0 and wrote_dml(conn) == []
+
+
+def test_dml_preview_promises_no_object_and_no_rollback_file():
+    """A DML statement is not a "new object", and the restore.sql generated
+    for it is a DROP nothing would accept — the preview must offer neither."""
+    import contextlib
+    import io
+    with tempfile.TemporaryDirectory() as td:
+        allow_dml(td)
+        out = io.StringIO()
+        with contextlib.redirect_stdout(out):
+            pythia.run_apply(FakeConn(dml_script()), "APP", dml_ns(td), DML_FILE)
+        text = out.getvalue()
+        assert "data_dml statement on APP" in text
+        assert "new object" not in text and "restore.sql" not in text
+
+
+def test_restore_refuses_an_entry_that_has_no_undo():
+    with tempfile.TemporaryDirectory() as td:
+        entry = pythia.write_journal_entry(
+            td, "DATA_DML", "STATEMENT", "",
+            "delete from t_order where id = 7",
+            {"connection": "DEV", "group": "data_dml", "applied": True})
+        ns = dml_ns(td, id=entry)
+        expect_exit(lambda: pythia.run_restore(FakeConn(base_script()),
+                                               "APP", ns),
+                    "no undo", "flashback")
+
+
+def test_deny_message_explains_what_revalidation_buys():
+    with tempfile.TemporaryDirectory() as td:
+        expect_exit(lambda: pythia.run_apply(FakeConn(dml_script()), "APP",
+                                             dml_ns(td), DML_FILE),
+                    "deny", "revalidation", "policy set data_dml confirm")
+
+
+def test_approve_records_the_row_set_it_showed():
+    with tempfile.TemporaryDirectory() as td:
+        allow_dml(td)
+        pythia.run_apply(FakeConn(dml_script(count=2)), "APP",
+                         dml_ns(td), DML_FILE)
+        meta = pythia.read_journal_entry(
+            td, pythia.list_journal_entries(td)[0])["meta"]
+        rec = pythia.mint_grant(
+            td, meta["token"], "DEV",
+            revalidate=pythia.fingerprint_text(meta["row_set"]))
+        assert rec["revalidate"].startswith("rows=2 hash=")
+        assert pythia.read_grant(td, meta["token"])["revalidate"] \
+            == rec["revalidate"]
+
+
+def test_insert_needs_no_row_set():
+    with tempfile.TemporaryDirectory() as td:
+        allow_dml(td)
+        conn = FakeConn(base_script())
+        code = pythia.run_apply(conn, "APP", dml_ns(td),
+                                "insert into t_order (id) values (1)\n")
+        assert code == 0
+        assert not [s for s, _ in conn.executed if "ora_hash" in s.lower()]
+        entry = pythia.list_journal_entries(td)[0]
+        assert pythia.read_journal_entry(td, entry)["meta"]["row_set"] is None
+
+
 def test_apply_preview_writes_nothing_and_gives_token():
     with tempfile.TemporaryDirectory() as td:
         conn = FakeConn(base_script())

{pythia_plsql-0.8.0 → pythia_plsql-0.9.0}/tests/test_phase5.py

@@ -98,7 +98,8 @@ def test_apply_skill_keeps_the_honest_rollback_table():
         return
     text = path.read_text(encoding="utf-8")
     for needle in ("Yes — completely", "Flashback Query", "Recycle Bin",
-                   "Almost never", "exit 3", "run-sql"):
+                   "Almost never", "exit 3", "run-sql",
+                   "revalidat"):                   # 0.9.0: the row-set gate
         assert needle in text, f"pythia-apply: missing {needle!r}"