{"id":51672548,"url":"https://github.com/muhdur/plsql-intelligence","last_synced_at":"2026-07-15T02:04:02.215Z","repository":{"id":361873822,"uuid":"1249438168","full_name":"MuhDur/plsql-intelligence","owner":"MuhDur","description":"Offline, package-aware Oracle PL/SQL code intelligence in Rust — change impact, dependency graph, honest uncertainty, self-healing coverage","archived":false,"fork":false,"pushed_at":"2026-06-27T17:03:20.000Z","size":12057,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T17:22:07.546Z","etag":null,"topics":["agent-tools","cargo-workspace","change-impact","code-intelligence","dba-tools","dependency-graph","mcp","mcp-server","oracle","oracle-database","oracle-plsql","pl-sql","plsql","rust","static-analysis"],"latest_commit_sha":null,"homepage":"https://github.com/MuhDur/plsql-intelligence","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MuhDur.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-25T17:44:42.000Z","updated_at":"2026-06-27T17:03:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MuhDur/plsql-intelligence","commit_stats":null,"previous_names":["muhdur/plsql-intelligence"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MuhDur/plsql-intelligence","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuhDur%2Fplsql-intelligence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuhDur%2Fplsql-intelligence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuhDur%2Fplsql-intelligence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuhDur%2Fplsql-intelligence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MuhDur","download_url":"https://codeload.github.com/MuhDur/plsql-intelligence/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuhDur%2Fplsql-intelligence/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35486976,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-15T02:00:06.706Z","response_time":131,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-tools","cargo-workspace","change-impact","code-intelligence","dba-tools","dependency-graph","mcp","mcp-server","oracle","oracle-database","oracle-plsql","pl-sql","plsql","rust","static-analysis"],"created_at":"2026-07-15T02:04:01.154Z","updated_at":"2026-07-15T02:04:02.210Z","avatar_url":"https://github.com/MuhDur.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PL/SQL Intelligence Engine\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\".github/assets/hero.svg\" alt=\"PL/SQL Intelligence Engine\" width=\"760\"\u003e\n\nOffline, package-aware Oracle PL/SQL code intelligence in Rust, with a\nself-healing coverage flywheel.\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![CI](https://github.com/MuhDur/plsql-intelligence/actions/workflows/ci.yml/badge.svg)](https://github.com/MuhDur/plsql-intelligence/actions/workflows/ci.yml)\n[![USR Loop](https://github.com/MuhDur/plsql-intelligence/actions/workflows/usr.yml/badge.svg)](https://github.com/MuhDur/plsql-intelligence/actions/workflows/usr.yml)\n[![License: Apache-2.0 OR MIT](https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg)](#license)\n[![unsafe: forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](#design-commitments)\n[![Rust stable channel](https://img.shields.io/badge/rust-stable-success.svg)](rust-toolchain.toml)\n\n\u003c/div\u003e\n\n\u003e Know what breaks before you change Oracle PL/SQL.\n\n```sh\n# Build the workspace and run the default test profile\ngit clone https://github.com/MuhDur/plsql-intelligence\ncd plsql-intelligence\ncargo build --workspace \u0026\u0026 cargo test --workspace\n```\n\n---\n\n## TL;DR\n\n**The problem.** In a large Oracle estate, PL/SQL packages, views,\ntriggers and tables form a deep dependency web. Change one column type or\none package spec and you can silently invalidate hundreds of downstream\nobjects; you find out in a failed production recompile. Existing tools\neach cover a slice (SQL deployment, lineage products, SAST scanners,\nOracle's own SQLcl MCP server), but none give offline, package-aware\nPL/SQL semantics with explicit uncertainty reporting, dependency\nreasoning, and recompile planning in one workflow.\n\n**The solution.** A layered Rust workspace that parses PL/SQL with a real\nANTLR backend, builds a semantic IR with name resolution and a dependency\ngraph, and reports change impact. When the analyzer cannot be certain it\nsays so, as a typed `UnknownReason`, instead of reporting a false-clean\nresult. That honest-uncertainty exhaust feeds the **USR Loop**, which\nturns recorded gaps into proven, privacy-clean parser and lowering\nrepairs so coverage compounds with use.\n\n### MCP belongs in `oraclemcp`\n\nThis repository now owns the offline PL/SQL engine, library crates, and\ncommand-line tools. MCP serving moved to the standalone\n[`oraclemcp`](https://github.com/MuhDur/oraclemcp) repository, where the\ndatabase connection layer and server lifecycle already live.\n\nThe old `plsql-mcp` workspace crate has been removed here. Published\nhistorical versions remain a compatibility path until the distribution\nretirement beads finish; new PL/SQL intelligence work should flow through\nthe library crates and the `plsql` / `plsql-depgraph` / `usr-loop` CLIs.\n\n\u003e _Independent open-source project; not affiliated with Oracle. Oracle client\n\u003e libraries are not included or required for the offline engine._\n\n### Why use it?\n\n| Capability | What it does |\n|------------|--------------|\n| **Offline-first** | Reads code and an Oracle catalog snapshot in place; no live database required for analysis, no telemetry by default |\n| **Real parser backend** | ANTLR-generated Rust parser code committed in `plsql-parser-antlr`, no JVM during normal builds, with a lossless token tape (`reconstruct(tape) == input`) |\n| **Honest uncertainty** | Where analysis cannot be certain it emits a typed `UnknownReason`; the completeness report is never false-clean |\n| **Dependency reasoning** | Semantic IR, name resolution, a privilege model, and a dependency graph cross-checkable against `ALL_DEPENDENCIES` |\n| **USR Loop** | A self-healing flywheel: captured gaps become privacy-proven fixtures, candidate patches, and a 9-stage fail-closed conformance gate |\n| **Verified accretion** | A monotone `coverage_index` with a CI tripwire makes \"coverage compounds\" a checked property, not a slogan |\n| **Memory safety** | The whole workspace is `#![forbid(unsafe_code)]` |\n\n### How it compares\n\n| | Live DB needed | Package-aware PL/SQL semantics | Honest uncertainty | Offline analysis |\n|---|:---:|:---:|:---:|:---:|\n| SQL deployment tools (Liquibase, Flyway) | yes | no | no | no |\n| Lineage / catalog products | varies | partial | no | varies |\n| Generic SAST scanners | no | no | no | yes |\n| Oracle SQLcl MCP server | yes | partial | no | no |\n| **PL/SQL Intelligence Engine** | **no** | **yes** | **yes** | **yes** |\n\n---\n\n## Status\n\nThe current line is the offline-pivot track for `0.7.0`. The workspace\nbuilds on the stable channel and no longer contains the `plsql-mcp` crate.\nThe project is still pre-1.0, so public APIs can move before the 1.0 line.\n`plan.md` remains the authoritative specification, and\n`docs/plans/2026-06-29-offline-pivot-retire-plsql-mcp.md` is the active\nretirement plan for the MCP split.\n\n- The Cargo workspace has 25 members: 20 product crates under `crates/`\n  plus 5 tool crates under `tools/`.\n- The normal source install path needs the stable-channel toolchain. Java is\n  only needed when regenerating the committed ANTLR parser output, not for\n  ordinary builds, tests, or CLI installation.\n- The product-facing binaries are `plsql`, `plsql-depgraph`, and\n  `usr-loop`. Each has `capabilities`, `robot-docs`, `doctor`, and\n  `--robot-json` / `--robot-triage` surfaces for agents.\n- MCP serving is now an `oraclemcp` responsibility. This repo exposes the\n  parser, semantic model, catalog snapshot model, dependency graph,\n  lineage, documentation, SAST, change-impact, and USR Loop library\n  surfaces that `oraclemcp` can consume.\n- The **USR Loop** is implemented end to end: the `plsql-accretion`\n  library, the `usr-loop` tool, the sha-pinned conformance gate, the\n  monotone tripwire, and the re-runnable acceptance proof\n  `scripts/usr_acceptance.sh`.\n- `AGENTS.md` describes how automated agents work in this repo.\n\n---\n\n## Testing and Verification\n\nThe default local profile is offline and stable-channel:\n\n- `cargo fmt --all -- --check`\n- `cargo clippy --workspace --all-targets -- -D warnings`\n- `cargo test --workspace --all-targets`\n- `cargo test --workspace --doc`\n- `cargo bench --workspace --no-run`\n- `cargo deny check`\n- `plan-lint`, corpus license checks, parse-success checks, lab goldens,\n  demo-no-db, offline honesty grep, offline boundary lint, and the USR\n  accretion gates.\n\nDo not read the test suite as \"there are no test doubles anywhere.\" The\nrepo contains deliberate test doubles where they pin a boundary: feature\noff live-XE sentinels, GitHub Action posting self-tests, fail-closed\nbindgen wrappers for invalid identifiers, hermetic Oracle connection\ndoubles, and the deterministic USR proposer path. Those are not unfinished\nproduction placeholders.\n\nThe private-estate Definition of Done is honest about its boundary. When\n`PLSQL_PRIVATE_ESTATE` is absent, `scripts/usr_acceptance.sh` exits\nsuccessfully with an `estate-absent` banner and does not claim the full\nestate proof. The binding full proof requires an estate-bearing host.\n\n---\n\n## Quick Example\n\n```sh\n# Build the workspace and run the default test profile\ncargo build --workspace\ncargo test --workspace\n\n# Inspect the CLI contracts agents should read first\ncargo run -p plsql-cicd --bin plsql -- capabilities\ncargo run -p plsql-depgraph -- capabilities\ncargo run -p usr-loop -- capabilities\n\n# Clippy with the project's deny-warning policy\ncargo clippy --workspace --all-targets -- -D warnings\n\n# Predict change impact from a directory, diff, or changeset artifact\ncargo run -p plsql-cicd --bin plsql -- predict ./changes --robot-json\n\n# Inspect a serialized dependency graph\ncargo run -p plsql-depgraph -- --graph depgraph.json doctor --robot-json\n\n# Drive the USR Loop against an estate (read in place, nothing copied out)\ncargo run -p usr-loop -- scan    /path/to/estate\ncargo run -p usr-loop -- cluster /path/to/estate\ncargo run -p usr-loop -- propose /path/to/estate --from-scan\ncargo run -p usr-loop -- doctor\n\n# The re-runnable Definition of Done for the USR Loop\nscripts/usr_acceptance.sh\n```\n\n---\n\n## The USR Loop (self-healing coverage flywheel)\n\nMost analyzers discard parse errors and unresolved references as failure.\nThis one records them as typed, provenanced, minimizable, offline\nartifacts, then repairs them. The full normative specification is\n`docs/plans/2026-05-19-usr-loop-self-healing-coverage-flywheel.md`; the\nrepair-class policy and gate honesty manifest are in\n`docs/decisions/D3-usr-repair-class-policy.md`.\n\n```\n estate (read in place; no byte copied out)\n   │  plsql-engine analyze → typed diagnostics + UnknownReason + provenance\n   ▼\n [A] GAP CAPTURE      filter repairable diagnostic classes → GapRecord\n   ▼                  (provenance only, never source bytes)\n [B] MINIMIZE +       smallest input that still triggers the same\n     PRIVACY-PROVE     signature; every literal/identifier re-synthesized;\n   ▼                  a redaction-delta manifest proves zero leak\n [C] CLUSTER/DEDUP    N occurrences → 1 GapCluster, K representative\n   ▼                  fixtures\n [D] PROPOSE          one candidate diff, exactly one repair class\n   ▼                  (g grammar / l lowering / d typed degradation)\n [E] CONFORMANCE GATE the 9-stage, fail-closed, sha-pinned bar\n   ▼ pass                       ▼ fail\n [F] LAND + LEDGER     [F'] QUARANTINE-AS-OPEN-BEAD\n   apply on branch,    file a provenanced bead naming the failing\n   add the fixture +   stage; the gate is never weakened to admit it\n   a pinned test,\n   append one\n   content-addressed\n   ledger entry\n   ▼\n [G] ACCRETION TRIPWIRE  the monotone coverage_index, CI-checked\n```\n\n### Invariants (the spec's spine; each is enforced, not aspirational)\n\n| Invariant | What it guarantees |\n|-----------|--------------------|\n| **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. |\n| **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. |\n| **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. |\n| **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. |\n| **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. |\n| **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. |\n| **I-MONOTONIC-VALUE** | The tracked `coverage_index` is monotone non-decreasing across releases. A release that lowers it fails CI. |\n\n### The conformance gate\n\n`scripts/usr_gate.sh` runs nine ordered stages, all must pass, fail-closed.\nAny non-pass rejects the candidate and files it as a bead; the gate is\nnever weakened to admit a patch.\n\n| Stage | Check |\n|-------|-------|\n| G1 | Builds: `plsql-parser-antlr --features antlr-codegen` and the workspace |\n| G2 | Lossless round-trip over the full corpus and every prior MinFixture |\n| G3 | Backend conformance (`plsql-parser/tests/conformance.rs`) |\n| G4 | Golden isomorphism, or an explicitly listed and justified golden delta |\n| G5 | Never-panic plus the fuzz targets, zero crashes |\n| G6 | Monotonic non-regression (`scripts/estate_correctness.sh`, metrics at or above baseline) |\n| G7 | Anti-gaming and honesty: diagnostics fall only with a commensurate extraction rise; posture not weakened |\n| G8 | Privacy: redaction-delta verified over the candidate and every added fixture; a leak aborts the run |\n| G9 | The added regression test is mutation-killed (fails if the patch is reverted) |\n\nThe gate script is content-pinned: `crates/plsql-accretion/gate.sha256`\nholds the expected `sha256` and `plsql-accretion`'s gate runner aborts on a\nmismatch. Changing the gate requires a deliberate, human-reviewed commit\nplus a sha bump. `crates/plsql-accretion/tests/gate_selftest.rs` feeds the\ngate an adversarial trio (a suppression-only patch, a privacy-leaking\nfixture, a round-trip-breaking patch) and asserts each is rejected at its\nnamed stage.\n\n### `coverage_index` and the tripwire\n\n```\ncoverage_index = extracted_semantics_ratio        (frozen public corpus\n                                                    benchmark, never\n                                                    private estate code)\n               + distinct_resolved_gap_signatures  (signature classes the\n                                                    loop has permanently\n                                                    closed, from the\n                                                    append-only ledger)\n```\n\n`scripts/accretion_tripwire.sh` (a required CI check) asserts\n`coverage_index(HEAD) \u003e= coverage_index(last release tag)` and\n`extracted_semantics_ratio(HEAD) \u003e= extracted_semantics_ratio(last release)`.\nFresh CI checkouts compare against the tracked deterministic seed in\n`crates/plsql-accretion/accretion_floor.json`, so the first floor is durable\neven though `.usr/ledger/` is scratch. A release that lowers either metric\nfails. The `coverage_index`-over-time table lives in `CHANGELOG.md`.\n\n### Definition of Done\n\n`scripts/usr_acceptance.sh` is the single re-runnable acceptance contract.\nIt is not a \"looks built\" check: it drives the loop to close a real,\ncurrently-open gap in a private estate end to end and asserts every\ninvariant held (provenance, privacy-proven fixture, gate exit 0 or correct\nquarantine, strict signature decrease, strict `extracted_semantics_ratio`\nincrease, preserved posture, ledger appended exactly once, mutation-killed\ntest, green adversarial gate self-test, byte-identical double run). When no\nprivate estate is configured the script exits 0 with a loud\n\"estate-absent\" banner, stating that the DoD is not proven in that\nenvironment. CI runs the full acceptance proof nightly\n(`.github/workflows/usr.yml`).\n\n---\n\n## Architecture\n\nThe workspace is layered (full detail in `plan.md` §5 and\n`docs/ARCHITECTURE.md`). Downstream crates never depend on ANTLR-generated\ntypes.\n\n| Layer | Crates | What it owns |\n|-------|--------|--------------|\n| 0   | `plsql-core`, `plsql-output`, `plsql-render`, `plsql-store` | Diagnostics, completeness/uncertainty, output shapes, content-addressed cache |\n| 1   | `plsql-parser`, `plsql-parser-antlr` | Backend-independent parser surface plus the ANTLR backend |\n| 1.5 | `plsql-catalog` | Oracle catalog snapshot model and stable row ingestion |\n| 2   | `plsql-ir`, `plsql-symbols`, `plsql-privileges`, `plsql-depgraph` | Semantic IR, name resolution, privilege model, dependency graph |\n| 3   | `plsql-engine` | Orchestration: per-run `AnalysisRun`, `CompletenessReport` |\n| 4   | `plsql-lineage`, `plsql-doc`, `plsql-bindgen`, `plsql-cicd`, `plsql-sast` | Lineage, docs, Rust bindings, change-set planning, static analysis |\n| 5   | `plsql-accretion`, `tools/usr-loop` | The USR Loop library and orchestrator |\n| External MCP | [`oraclemcp`](https://github.com/MuhDur/oraclemcp) | MCP server, Oracle connection lifecycle, guarded live access, and optional integration with these engine crates |\n\n```\n  PL/SQL source + Oracle catalog snapshot\n              │\n              ▼\n   plsql-parser-antlr (lossless tape + AST)\n              │\n              ▼\n   plsql-ir → plsql-symbols → plsql-depgraph\n              │\n              ▼\n   plsql-engine: AnalysisRun + CompletenessReport\n        │                    │\n        ▼                    ▼\n  product surfaces      typed UnknownReason exhaust\n  (lineage / docs /           │\n   bindings / cicd /          ▼\n   sast)               plsql-accretion + usr-loop\n                       (capture → fixture → gate → land)\n```\n\nTool binaries: `plsql` (change-impact, docs, SAST, doctor),\n`plsql-depgraph` (dependency graph query/explain/doctor), `usr-loop`\n(the USR Loop orchestrator), `plan-lint`, `corpus-license-check`,\n`corpus-bench`, and `corpus-grow`.\n\nMCP is intentionally not a binary in this workspace anymore. Agents that\nneed a server should use `oraclemcp`; agents that need offline PL/SQL\nintelligence should call the library crates directly or use the CLIs.\n\n---\n\n## Installation\n\nThe workspace builds with the stable channel pinned in `rust-toolchain.toml`.\nThe workspace MSRV is recorded in `Cargo.toml` as `rust-version = \"1.96\"`.\nNormal installation does not require Java. Java is only needed when a\nmaintainer explicitly regenerates the ANTLR parser output.\n\n### Install Released CLIs\n\nLinux and macOS:\n\n```sh\ncurl -fsSL \"https://github.com/MuhDur/plsql-intelligence/releases/latest/download/install.sh?$(date +%s)\" | bash\n```\n\nWindows PowerShell:\n\n```powershell\nirm \"https://github.com/MuhDur/plsql-intelligence/releases/latest/download/install.ps1?$([DateTimeOffset]::UtcNow.ToUnixTimeSeconds())\" | iex\n```\n\nThe installers fetch the latest GitHub release, verify `SHA256SUMS`, install\n`plsql` and `plsql-depgraph`, and print uninstall instructions.\n\n### From source\n\n```sh\ngit clone https://github.com/MuhDur/plsql-intelligence\ncd plsql-intelligence\ncargo build --workspace --release\n```\n\n### Install CLIs from a checkout\n\n```sh\ncargo install --path crates/plsql-cicd --bin plsql\ncargo install --path crates/plsql-depgraph\ncargo install --path tools/usr-loop\n```\n\n### Install CLIs from Git\n\n```sh\ncargo install --git https://github.com/MuhDur/plsql-intelligence --package plsql-cicd --bin plsql\ncargo install --git https://github.com/MuhDur/plsql-intelligence --package plsql-depgraph\ncargo install --git https://github.com/MuhDur/plsql-intelligence --package usr-loop\n```\n\n### Per-crate iteration\n\nPer-crate builds keep cycles short during development:\n\n```sh\ncargo build -p plsql-catalog\ncargo test  -p plsql-accretion\n```\n\nNo Oracle client or database connection is required for the default\noffline CLIs.\n\n---\n\n## Command Reference\n\nGlobal discovery commands exist on the main user-facing binaries:\n\n```sh\n\u003cbinary\u003e capabilities       # machine-readable agent contract\n\u003cbinary\u003e robot-docs         # concise agent handbook\n\u003cbinary\u003e --robot-triage     # capabilities + health + quick reference\n\u003cbinary\u003e doctor             # local health report\n```\n\n### `plsql`\n\nThe release-assurance CLI for change impact, rendered documentation, SAST\nartifacts, and local diagnostics.\n\n```sh\nplsql predict ./changes --robot-json\nplsql predict --git-range main..HEAD --repo .\nplsql doc docset.json --format markdown --robot-json\nplsql sast scan-report.json --format sarif --robot-json\nplsql doctor ./changes --robot-json\nplsql capabilities\nplsql robot-docs\n```\n\n### `plsql-depgraph`\n\nRead a serialized dependency graph and query or explain it.\n\n```sh\nplsql-depgraph --graph depgraph.json doctor --robot-json\nplsql-depgraph --graph depgraph.json query reverse-neighbors --logical-id HR.PKG_ORDERS\nplsql-depgraph --graph depgraph.json query path --from-logical-id HR.PKG_ORDERS --to-logical-id HR.TABLE_ORDERS\nplsql-depgraph --graph depgraph.json explain --logical-id HR.PKG_ORDERS --robot-json\nplsql-depgraph capabilities\n```\n\n### `usr-loop`\n\nThe USR Loop orchestrator. A global `--robot-json` flag emits a single-line\nmachine-readable envelope on every subcommand.\n\n```sh\nusr-loop scan    \u003cestate\u003e                  # [A] capture GapRecords\nusr-loop cluster \u003cestate\u003e                  # [C] deduped GapClusters\nusr-loop propose \u003cestate\u003e --from-scan      # [D] one candidate diff\nusr-loop propose \u003cestate\u003e --cluster-id ID  # propose for a specific signature\nusr-loop gate    \u003ccandidate-diff\u003e          # run the sha-pinned §3 gate\nusr-loop land    \u003ccandidate\u003e --fixture F   # [F] gate, then land or quarantine\nusr-loop ledger  \u003caction\u003e                  # inspect the append-only ledger\nusr-loop doctor                            # crate/schema versions, deps\n```\n\nExit codes for `gate`/`land`: `0` accepted/landed, `3` rejected/quarantined\n(spec-correct, not a bug), `4` gate sha-pin abort, `9` I-PRIVACY abort\n(nothing persisted).\n\n### `plan-lint`\n\n```sh\ncargo run -p plan-lint --              # structural lint of plan.md\ncargo run -p plan-lint -- --robot-json # machine-readable findings\ncargo run -p plan-lint -- --doctor     # health summary\n```\n\n---\n\n## Design Commitments\n\n- Rust Cargo workspace, one crate per component.\n- `doctor` subcommands and `--robot-json` output on every CLI surface, so\n  agents read the machine contract instead of guessing.\n- Explicit `UnknownReason` records whenever analysis cannot be certain; the\n  completeness report is never false-clean.\n- Parser backend isolation: downstream crates must not depend on\n  ANTLR-generated types.\n- The whole workspace is `#![forbid(unsafe_code)]`.\n- No telemetry by default.\n\n---\n\n## Repository Workflow\n\n1. Read `AGENTS.md` and `plan.md` first.\n2. Treat `plan.md` as the source of truth for intended architecture and\n   scope. If code and `plan.md` diverge, fix one or the other deliberately.\n3. Track work in Beads only; `.beads/` is authoritative.\n4. Never copy private material into this repository. The USR Loop and the\n   correctness harness read a private estate in place, at the path given\n   by the `PLSQL_PRIVATE_ESTATE` environment variable, and never persist\n   its bytes.\n\n---\n\n## Layout\n\n- `plan.md`: master specification\n- `AGENTS.md`: repo operating rules\n- `Cargo.toml`, `crates/`, `tools/`: Rust workspace\n- `corpus/`: public and synthetic PL/SQL fixtures used by tests\n- `docs/`: architecture snapshot, plans, decisions, integration guides\n- `scripts/`: `usr_gate.sh`, `usr_acceptance.sh`, `accretion_tripwire.sh`,\n  `estate_correctness.sh`\n- `.beads/`: Beads issue-tracker state (authoritative)\n- `CHANGELOG.md`: release-notes log plus the `coverage_index` table\n\n---\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---------|-----|\n| `usr-loop gate` exits 4 | Gate sha-pin mismatch. The gate script changed without a sha bump in `crates/plsql-accretion/gate.sha256`. This is intentional fail-closed behavior; re-pin only via a reviewed commit. |\n| `usr-loop gate`/`land` exits 9 | An I-PRIVACY leak signal at G8. The run aborted and persisted nothing, by design. Inspect the offending fixture; do not weaken G8. |\n| `usr_acceptance.sh` exits 0 with an \"estate-absent\" banner | No private estate is configured (`PLSQL_PRIVATE_ESTATE` unset or empty), so the DoD is not proven here. Run it with the variable pointing at a private estate, or rely on nightly CI. |\n| Parser regeneration fails | Normal builds use committed generated Rust. Regeneration is maintainer work: install Java, set `PLSQL_ANTLR_REGEN=1`, then run the parser drift-check path. |\n| Empty dependency graph on a real estate | Expected for the dialect tail the parser cannot yet reach; those are recorded as typed `UnknownReason` and are exactly the USR Loop's repair input, not a silent failure. |\n\n---\n\n## Limitations\n\n- Pre-1.0: the API can move at any time before 1.0.\n- This repository is not the MCP server anymore. Use `oraclemcp` for MCP\n  serving, Oracle sessions, and guarded live database access.\n- Live Oracle extraction is not in this repository. Use `oraclemcp` for\n  Oracle sessions, live catalog snapshots, and guarded database access.\n- The USR Loop proposer does not auto-merge. It produces proven\n  candidates; the proof is automatic and complete, the landing decision is\n  gated by that proof and the repo's normal review (per `D3`).\n- Genuinely-ambiguous Oracle dialect forms are not resolved by guessing.\n  They become honest typed `UnknownReason` (repair-class `d`): coverage of\n  honesty, never of fabrication.\n- Accretion compounds on signature classes, not raw counts. A long tail of\n  singleton estate quirks may stay open; that is reported, not masked.\n- Class-`g` grammar patches are real grammar work, gated like everything\n  else: slower, but sound.\n- Referential-integrity subsetting is routed to a separate future plan, not\n  the first release.\n\n---\n\n## FAQ\n\n**Does analysis require a live Oracle database?** No. Analysis is offline\nagainst source plus an optional catalog snapshot. Live Oracle access belongs\nin `oraclemcp`; this repo keeps the offline engine and CLIs.\n\n**Is the parser real, or a heuristic scanner?** Real. The engine parses\nthrough the ANTLR-generated Rust backend in `plsql-parser-antlr` with a\nlossless token tape; the decision and evidence are in\n`docs/decisions/D2-backend-final.md`.\n\n**What happens to constructs the parser cannot handle?** They are recorded\nas typed `UnknownReason` with provenance. The completeness report reflects\nthat honestly instead of reporting a false-clean result.\n\n**Has the USR Loop closed N gaps on a real estate?** That claim is not\nmade here as a settled marketing fact. The mechanism is implemented and\nthe proof is the re-runnable `scripts/usr_acceptance.sh` plus nightly CI.\nThis README documents how to run it, not an unverifiable boast.\n\n**Can I weaken the gate to land a patch faster?** No. The gate is\nsha-pinned and fail-closed; a mismatch aborts. Changing it requires a\nreviewed commit and a deliberate sha bump.\n\n**Is any code `unsafe`?** No. The whole workspace is\n`#![forbid(unsafe_code)]`.\n\n---\n\n## License\n\nDual-licensed under either of:\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))\n- MIT license ([LICENSE-MIT](LICENSE-MIT))\n\nat your option. The vendored ANTLR PL/SQL grammar under\n`crates/plsql-parser-antlr/grammars/` is Apache-2.0, from\n`antlr/grammars-v4`; attribution is preserved in\n`crates/plsql-parser-antlr/LICENSE-GRAMMARS.md`.\n\nUnless you explicitly state otherwise, any contribution intentionally\nsubmitted for inclusion in the work by you, as defined in the Apache-2.0\nlicense, shall be dual-licensed as above, without any additional terms or\nconditions.\n\n---\n\n## About Contributions\n\n*About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other \"stakeholders,\" which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.\n\n\n---\n\n### Work with me\n\nI help enterprises with the hard parts: databases at scale, systems modernization, and AI in production, vendor-neutral (cloud or self-hosted). Building something hard in databases, Rust / C++, or AI? Reach out.\n\n→ **[durakovic.ai](https://durakovic.ai)** · hello@durakovic.ai\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuhdur%2Fplsql-intelligence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuhdur%2Fplsql-intelligence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuhdur%2Fplsql-intelligence/lists"}