PL/SQL Intelligence

PL/SQL Intelligence Engine

Offline, package-aware Oracle PL/SQL code intelligence in Rust, with a self-healing coverage flywheel.

[](https://github.com/MuhDur/plsql-intelligence/actions/workflows/ci.yml) [](https://github.com/MuhDur/plsql-intelligence/actions/workflows/usr.yml) [](#license) [](#design-commitments) [](rust-toolchain.toml)

> Know what breaks before you change Oracle PL/SQL.

# Build the whole workspace and run every test
git clone https://github.com/MuhDur/plsql-intelligence
cd plsql-intelligence
cargo build --workspace && cargo test --workspace

---

TL;DR

The problem. In a large Oracle estate, PL/SQL packages, views, triggers and tables form a deep dependency web. Change one column type or one package spec and you can silently invalidate hundreds of downstream objects; you find out in a failed production recompile. Existing tools each cover a slice (SQL deployment, lineage products, SAST scanners, Oracle's own SQLcl MCP server), but none give offline, package-aware PL/SQL semantics with explicit uncertainty reporting, dependency reasoning, and recompile planning in one workflow.

The solution. A layered Rust workspace that parses PL/SQL with a real ANTLR backend, builds a semantic IR with name resolution and a dependency graph, and reports change impact. When the analyzer cannot be certain it says so, as a typed UnknownReason, instead of reporting a false-clean result. That honest-uncertainty exhaust feeds the USR Loop, which turns recorded gaps into proven, privacy-clean parser and lowering repairs so coverage compounds with use.

Two MCP servers: oraclemcp and plsql-mcp

This repo ships the full PL/SQL Intelligence MCP server, plsql-mcp — live Oracle DB tools plus offline PL/SQL intelligence (parse/analyze, dependency graph, lineage, SAST) and guarded writes. Its engine-free core was extracted to a standalone, published sibling, oraclemcp:

| | oraclemcp | plsql-mcp (this repo) | |---|---|---| | Scope | Guarded live Oracle DB access | The superset: DB access + PL/SQL intelligence + guarded writes | | Build | Engine-free, lean, fast | Full pure-Rust ANTLR engine | | Install | cargo install oraclemcp · docker run -i ghcr.io/muhdur/oraclemcp | cargo install --path crates/plsql-mcp · docker run -i ghcr.io/muhdur/plsql-mcp | | MCP registry | io.github.MuhDur/oraclemcp | io.github.MuhDur/plsql-mcp |

Reach for oraclemcp when an agent just needs governed database access; use plsql-mcp when you want deep PL/SQL code understanding (it includes everything oraclemcp does).

> Independent open-source project; not affiliated with Oracle. The Docker images > ship the project binaries only; they do not bundle Oracle Instant Client.

Why use it?

| Capability | What it does | |------------|--------------| | Offline-first | Reads code and an Oracle catalog snapshot in place; no live database required for analysis, no telemetry by default | | Real parser backend | antlr4rust (plsql-parser-antlr), pure Rust, no JVM, with a lossless token tape (reconstruct(tape) == input) | | Honest uncertainty | Where analysis cannot be certain it emits a typed UnknownReason; the completeness report is never false-clean | | Dependency reasoning | Semantic IR, name resolution, a privilege model, and a dependency graph cross-checkable against ALL_DEPENDENCIES | | USR Loop | A self-healing flywheel: captured gaps become privacy-proven fixtures, candidate patches, and a 9-stage fail-closed conformance gate | | Verified accretion | A monotone coverage_index with a CI tripwire makes "coverage compounds" a checked property, not a slogan | | Memory safety | The whole workspace is #![forbid(unsafe_code)] |

How it compares

| | Live DB needed | Package-aware PL/SQL semantics | Honest uncertainty | Offline analysis | |---|:---:|:---:|:---:|:---:| | SQL deployment tools (Liquibase, Flyway) | yes | no | no | no | | Lineage / catalog products | varies | partial | no | varies | | Generic SAST scanners | no | no | no | yes | | Oracle SQLcl MCP server | yes | partial | no | no | | PL/SQL Intelligence Engine | no | yes | yes | yes |

---

Status

This is pre-1.0 software under active development. plan.md is the authoritative specification; docs/ARCHITECTURE.md is the technical architecture snapshot.

• The Cargo workspace ships 22 plsql-* engine and analysis crates plus 5

tool binaries (crates/, tools/). The engine-free MCP server core (8 oraclemcp-* crates: protocol, tool registry, the fail-closed SQL guard, audit sink, auth, telemetry, config, error envelope) was extracted to the standalone, published oraclemcp repo; plsql-mcp now consumes them from crates.io. The one-way boundary (oraclemcp-* never imports a plsql-* engine crate) holds by construction and is enforced in the oraclemcp repo's CI. The foundation and product layers are implemented; live Oracle catalog extraction, the verify/CI-cascade path, and the live-DB MCP tool surface are feature-gated and exercised against a containerized Oracle 23ai (live-xe suites, make demo-oracle-xe-ci).

• The USR Loop (Layer 5) is implemented end to end: the

plsql-accretion library, the usr-loop tool, the sha-pinned conformance gate, the monotone tripwire, and the re-runnable acceptance proof scripts/usr_acceptance.sh.

• The API can change before 1.0.
• AGENTS.md describes how automated agents work in this repo.

---

Quick Example

# Build the workspace and run the full test suite
cargo build --workspace
cargo test --workspace

# Clippy with the project's deny-warning policy
cargo clippy --workspace --all-targets -- -D warnings

# Inspect the MCP server and its machine-readable contract
cargo run -p plsql-mcp -- info
cargo run -p plsql-mcp -- --robot-json capabilities

# Drive the USR Loop against an estate (read in place, nothing copied out)
cargo run -p usr-loop -- scan    /path/to/estate
cargo run -p usr-loop -- cluster /path/to/estate
cargo run -p usr-loop -- propose /path/to/estate --from-scan
cargo run -p usr-loop -- doctor

# The re-runnable Definition of Done for the USR Loop
scripts/usr_acceptance.sh

---

The USR Loop (self-healing coverage flywheel)

Most analyzers discard parse errors and unresolved references as failure. This one records them as typed, provenanced, minimizable, offline artifacts, then repairs them. The full normative specification is docs/plans/2026-05-19-usr-loop-self-healing-coverage-flywheel.md; the repair-class policy and gate honesty manifest are in docs/decisions/D3-usr-repair-class-policy.md.

 estate (read in place; no byte copied out)
   │  plsql-engine analyze → typed diagnostics + UnknownReason + provenance
   ▼
 [A] GAP CAPTURE      filter repairable diagnostic classes → GapRecord
   ▼                  (provenance only, never source bytes)
 [B] MINIMIZE +       smallest input that still triggers the same
     PRIVACY-PROVE     signature; every literal/identifier re-synthesized;
   ▼                  a redaction-delta manifest proves zero leak
 [C] CLUSTER/DEDUP    N occurrences → 1 GapCluster, K representative
   ▼                  fixtures
 [D] PROPOSE          one candidate diff, exactly one repair class
   ▼                  (g grammar / l lowering / d typed degradation)
 [E] CONFORMANCE GATE the 9-stage, fail-closed, sha-pinned bar
   ▼ pass                       ▼ fail
 [F] LAND + LEDGER     [F'] QUARANTINE-AS-OPEN-BEAD
   apply on branch,    file a provenanced bead naming the failing
   add the fixture +   stage; the gate is never weakened to admit it
   a pinned test,
   append one
   content-addressed
   ledger entry
   ▼
 [G] ACCRETION TRIPWIRE  the monotone coverage_index, CI-checked

Invariants (the spec's spine; each is enforced, not aspirational)

| Invariant | What it guarantees | |-----------|--------------------| | I-PRIVACY | No customer byte leaves the estate. Every persisted artifact is a re-synthesized, structurally-equivalent minimal reproduction, proven leak-free per artifact (gate stage G8). A failed privacy proof aborts the run and persists nothing. | | I-NO-REGRESSION | A patch lands only if proven behavior-preserving on the whole corpus: lossless round-trip, backend conformance, golden isomorphism, monotonic non-regression. Propose, prove, then land; never auto-merge unproven. | | I-NO-GAMING | A coverage gain counts only with a commensurate, measured rise in extracted semantics for the targeted signature. Suppressing a diagnostic to "fix" a gap is auto-rejected at G7. | | I-DETERMINISM | Same estate plus same engine commit yields byte-identical gap records, fixtures, signatures, and candidate set. No wall-clock, no RNG, no map-iteration order in any persisted artifact. | | I-PROVENANCE | Every record, fixture, candidate, verdict, and landed patch is content-addressed and traces estate-run to diagnostic to fixture to diff to gate result. The ledger is append-only. | | I-ISOLATION | Patches touch only the .g4 grammar, plsql-parser-antlr codegen / lowering, or the typed-degradation classifier; never make a downstream crate depend on ANTLR types or break public contracts non-additively. | | I-MONOTONIC-VALUE | The tracked coverage_index is monotone non-decreasing across releases. A release that lowers it fails CI. |

The conformance gate

scripts/usr_gate.sh runs nine ordered stages, all must pass, fail-closed. Any non-pass rejects the candidate and files it as a bead; the gate is never weakened to admit a patch.

| Stage | Check | |-------|-------| | G1 | Builds: plsql-parser-antlr --features antlr-codegen and the workspace | | G2 | Lossless round-trip over the full corpus and every prior MinFixture | | G3 | Backend conformance (plsql-parser/tests/conformance.rs) | | G4 | Golden isomorphism, or an explicitly listed and justified golden delta | | G5 | Never-panic plus the fuzz targets, zero crashes | | G6 | Monotonic non-regression (scripts/estate_correctness.sh, metrics at or above baseline) | | G7 | Anti-gaming and honesty: diagnostics fall only with a commensurate extraction rise; posture not weakened | | G8 | Privacy: redaction-delta verified over the candidate and every added fixture; a leak aborts the run | | G9 | The added regression test is mutation-killed (fails if the patch is reverted) |

The gate script is content-pinned: crates/plsql-accretion/gate.sha256 holds the expected sha256 and plsql-accretion's gate runner aborts on a mismatch. Changing the gate requires a deliberate, human-reviewed commit plus a sha bump. crates/plsql-accretion/tests/gate_selftest.rs feeds the gate an adversarial trio (a suppression-only patch, a privacy-leaking fixture, a round-trip-breaking patch) and asserts each is rejected at its named stage.

coverage_index and the tripwire

coverage_index = extracted_semantics_ratio        (frozen public corpus
                                                    benchmark, never
                                                    private estate code)
               + distinct_resolved_gap_signatures  (signature classes the
                                                    loop has permanently
                                                    closed, from the
                                                    append-only ledger)

scripts/accretion_tripwire.sh (a required CI check) asserts coverage_index(HEAD) >= coverage_index(last release tag). A release that lowers it fails. The coverage_index-over-time table lives in CHANGELOG.md; the first release seeds the monotone floor deterministically.

Definition of Done

scripts/usr_acceptance.sh is the single re-runnable acceptance contract. It is not a "looks built" check: it drives the loop to close a real, currently-open gap in a private estate end to end and asserts every invariant held (provenance, privacy-proven fixture, gate exit 0 or correct quarantine, strict signature decrease, strict extracted_semantics_ratio increase, preserved posture, ledger appended exactly once, mutation-killed test, green adversarial gate self-test, byte-identical double run). When no private estate is configured the script exits 0 with a loud "estate-absent" banner, stating that the DoD is not proven in that environment. CI runs the full acceptance proof nightly (.github/workflows/usr.yml).

---

Architecture

The workspace is layered (full detail in plan.md §5 and docs/ARCHITECTURE.md). Downstream crates never depend on ANTLR-generated types.

| Layer | Crates | What it owns | |-------|--------|--------------| | 0 | plsql-core, plsql-output, plsql-render, plsql-store | Diagnostics, completeness/uncertainty, output shapes, content-addressed cache | | 1 | plsql-parser, plsql-parser-antlr | Backend-independent parser surface plus the ANTLR backend | | 1.5 | plsql-catalog | Oracle catalog snapshot model plus live extraction | | 2 | plsql-ir, plsql-symbols, plsql-privileges, plsql-depgraph | Semantic IR, name resolution, privilege model, dependency graph | | 3 | plsql-engine | Orchestration: per-run AnalysisRun, CompletenessReport | | 4 | plsql-lineage, plsql-doc, plsql-bindgen, plsql-cicd, plsql-sast | Lineage, docs, Rust bindings, change-set planning, static analysis | | 5 | plsql-mcp, plsql-accretion | The unified MCP server plus the USR Loop library (no reverse deps) | | MCP core (external) | oraclemcp-core, oraclemcp-guard, oraclemcp-db, oraclemcp-audit, oraclemcp-auth, oraclemcp-telemetry, oraclemcp-config, oraclemcp-error | Engine-free MCP server core: protocol/registry, the fail-closed SQL guard and operating-level state, the connection layer, the out-of-band audit sink, transport auth, telemetry, config, and the structured error envelope. #![forbid(unsafe_code)]; never imports a plsql-* engine crate (one-way boundary). Extracted to the standalone oraclemcp repo and consumed from crates.io: plsql-mcp depends on the published oraclemcp-core/-guard/-error rather than in-workspace copies |

  PL/SQL source + Oracle catalog snapshot
              │
              ▼
   plsql-parser-antlr (lossless tape + AST)
              │
              ▼
   plsql-ir → plsql-symbols → plsql-depgraph
              │
              ▼
   plsql-engine: AnalysisRun + CompletenessReport
        │                    │
        ▼                    ▼
  product surfaces      typed UnknownReason exhaust
  (lineage / docs /           │
   bindings / cicd /          ▼
   sast)               plsql-accretion + usr-loop
                       (capture → fixture → gate → land)

Tool binaries: tools/usr-loop (the USR Loop orchestrator), tools/plan-lint (structural lint of plan.md), tools/corpus-license-check, tools/corpus-bench, tools/corpus-grow.

The MCP server (plsql-mcp) is a single binary built on the engine-free oraclemcp-* core. It completes the MCP handshake, advertises the full tool surface over tools/list — each tool carries a real argument JSON-Schema and read-only / destructive annotations — and dispatches tools/call end-to-end: static-analysis and change-impact tools execute in-process; live-DB tools dispatch and degrade with a typed RuntimeStateRequired response (naming the tool to call next) when no active Oracle connection is configured. A zero-argument oracle_capabilities tool reports the feature flags and surface so an agent can orient before its first call, and failed calls return a structured error envelope with a machine-readable class and a fuzzy "did you mean" suggestion. A lockstep test enforces that every tool the registry advertises has a d

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MuhDur
• Source: MuhDur/plsql-intelligence
• License: Apache-2.0
• Homepage: https://github.com/MuhDur/plsql-intelligence

Install and usage instructions live in the source repository linked above.