plan.md

# PL/SQL Intelligence Engine — Master Plan

> **Status:** DRAFT v0.13 — offline pivot reconciliation. The active architecture is now a stable-channel, offline PL/SQL engine plus CLI workspace. The former in-repo `plsql-mcp` server surface is retired from this repo; MCP serving and live Oracle sessions belong in the separate `oraclemcp` repository, which may consume these engine crates as libraries. Historical `plsql-mcp` design text remains in the version log and retired notes only.
> **Status (previous):** DRAFT v0.12 — catalog live-loader API correction (round 10). The catalog snapshot is now explicitly serialized with its `SymbolInterner`, which exposed a real API flaw in the prior live-loader signature: `schemas: &[SchemaName]` was not self-describing outside the originating interner context. Resolution: replace the public live-loader input with `CatalogLoadRequest { schema_filters: Vec<CatalogSchemaFilter> }`, where filters are text-backed (`CurrentSchema` or `Named(String)`) and therefore safe to pass across CLI / JSON / test boundaries without hidden symbol-table coupling. `PLSQL-CAT-019` is added as the discovered design-correction bead, and `PLSQL-CAT-004` now depends on it.
> **Status (previous):** DRAFT v0.9 — post-duel follow-up amendments round (round 7) integrated. Three of the five duel follow-ups landed; two explicitly rejected. Engineering architecture still unchanged; what this round adds: one new product surface (`plsql-mcp` Apache + `plsql-mcp-pro` FSL — §13A MCP Adapter Surface, resolves the duel's most strategically interesting unresolved fork by giving the foundation-OSS tier a viral dev-tool surface and the commercial tier a license-gated upsell hook inside the same workflow); one new operational program (§1.6 Commercial Validation Track — productized $25k–$40k fixed-fee design-partner Impact Assessment with hard guardrails: max 2 concurrent / max 6 total engagements pre-commercial-GA, warm-intro-only, on-prem tooling only, no-custom-feature contract clause, standard report template, ICP qualifier filter); one narrowly-scoped internal workflow (§18.11.1 internal support-only repro minimization — parser-level structural minimization of customer support bundles into corpus fixtures with mandatory human review, never customer-facing, never marketed). Two follow-ups rejected by operator: `ApplicationEndpoint` placeholder node in `plsql-depgraph` (Phase-2 APEX / Java-caller / scheduler-job ingestion hook — left for a future plan), pre-amendment market-fork experiments (posting `plsql-mcp` to r/oracle + HN and cold-outreach 5 release-engineering leads — operator chose to land the MCP split directly without the experiment gate). Twenty-seven new bead seeds across MCP / CVT / SUPPORT families. License stack expanded: `plsql-mcp` joins the Apache-2.0 OR MIT row; `plsql-mcp-pro` joins the FSL row per D8. Track B (live-DB Oracle MCP) re-clarified in §2.2 as distinct from the in-scope engine-MCP — wider live-session scope remains a separate project.
> **Status (previous):** DRAFT v0.8 — dueling-wizards synthesis round (round 6) integrated. Six consensus-winning ideas from an adversarial Codex (gpt-5.5 xhigh) vs Gemini 3 Pro duel landed as commercial-design plan amendments (architecture unchanged): §1.4 Commercial Nucleus declares *"Oracle Change Impact + Recompile Assurance"* as the single paid buying story with three-SKU framing and a canonical DROP COLUMN hero demo; §1.5 Evidence UX Release Gate promotes CompletenessReport/UnknownReason/DynamicSqlEvidence to the central product UX with a mandatory Trust Block on every customer report (no fake scalar score); §6.2.8.1 `corpus/lab/` adds a public synthetic Oracle estate doubling as sales demo + self-serve eval + AI-swarm regression target + golden test suite (L1→L2→L3 layered build, `make demo-no-db` / `make demo-oracle-xe`); D19 reopened to permit foundation-OSS `0.x.y` adoption-tier releases ahead of commercial GA (commercial GA-is-1.0 still stands for the paid tiers); §14.7 PR Integration adds `plsql gate --pr-comment-json` + CI templates + `plsql post-pr-comment` self-hosted poster (no hosted GitHub App — violates R17); §13.8 Orphan Candidates Report adds confidence-tiered cleanup/security-posture artifact with mandatory 30/60/90-day AUDIT-based observation windows (no "drop tomorrow" language, AUDIT statements only — no DROP scripts). Twenty-five new bead seeds across LAB / CICD / LIN families. Five follow-up amendments documented in `DUELING_WIZARDS_REPORT.md` await separate operator approval (Commercial Validation Track, ApplicationEndpoint placeholder, redacted-repro reframing, MCP split, market-fork experiments).
> **Status (previous):** DRAFT v0.7 — round-5 GPT-Pro refinement integrated. Final consistency pass approaching steady-state: out-of-scope work items (`PLSQL-BG-X01`/`X02`, subsetter SUB-* entries, `PLSQL-RELEASE-002`) no longer carry bead-IDs that `beads-workflow` could convert; D9 vs §16.7 stub-masking contradiction closed; bead-graph hygiene pass relocated `PLSQL-CORE-IDS-001` + `PLSQL-SUPPORT-*` + `PLSQL-PERF-*` + `PLSQL-STORE-DAEMON-*` to the correct layer tables; PL/Scope diff beads renamed `PLSCOPE-DIFF-001/002` and moved to Layer 2 to honor their actual dependencies; corpus layout now includes `db-fixtures/`; residual wedge wording cleaned in §6.2.5, §7.2, §12.1, §13.1, §18.2; `plsql-privileges` acceptance criteria tightened from one line to five concrete gates; `plsql-flow` and `plsql-facts` acceptance criteria made falsifiable with golden snapshots + per-surface integration tests; SAST harness depends on `FactStore`/`AnalysisRun` instead of raw semantic model; PLAN-003 target renumbering scheme specified explicitly; D15 candidates pruned (rejected `PLOracle` for trademark-confusion risk).
> **Status (previous):** DRAFT v0.6 — round-4 GPT-Pro refinement integrated. Consistency cleanup, not architectural rework: §2.1 engine row corrected to Layer 2.5; §5 diagram split into separate Layer 3 (scan/doc/bindgen), Layer 4 (lineage), Layer 5 (cicd); added §10A Layer 2.5 section with engine acceptance criteria; moved ENG-001..005 out of Layer 0; fixed two real dependency cycles (SQLSEM→DEP, FLOW→SAST); added acceptance criteria for sqlsem/flow/facts; expanded `AnalysisRun` with flow + facts + manifest; aligned bindgen REF cursor type map with hard-parts text; fixed pipelined functions in hazards table; refreshed R6 (corpus dirs) + R7 (async runtime reflects daemon); naming/licensing tables now list every crate; replaced `[DEFERRED]` with `[FUTURE-PLAN]`/`[OUT-OF-SCOPE]`; plan-lint changelog-whitelist + number-normalization bead added; D19 reworded to "GA is 1.0"; K1/K7 mitigations refreshed; added §18.4 parser-backend packaging policy; DBMS_ASSERT reclassified as sanitizer family (presence is evidence, not safety proof).
> **Owner:** Durak (engineering persona) acting on founder's behalf — this is a personal-business plan executed in the founder's private workspace.
> **Project key:** `plsql-intelligence`
> **Created:** 2026-05-11
> **Source ideas:** `/home/md/carriercall/workspace/initial-ideas.md`
> **Bead label:** `project:plsql-intelligence` on every related bead (CLAUDE.md Rule 3 — never `br sync`)
> **Convention:** This plan is structured by **architectural layers and component dependencies**, not by timelines, phases, waves, or MVPs. Every unit is independently testable; every dependency is explicit; the document is designed for mechanical transfer to beads via the `beads-workflow` skill.

---

## Table of Contents

0. [Document conventions](#0-document-conventions)
1. [Identity](#1-identity)
2. [Scope](#2-scope)
3. [Founder constraints](#3-founder-constraints)
4. [Architectural rules (R-rules)](#4-architectural-rules)
5. [Dependency graph](#5-dependency-graph)
6. [Layer 0 — Foundations](#6-layer-0--foundations)
7. [Layer 1 — Parser Core](#7-layer-1--parser-core)
8. [Layer 1.5 — Oracle Context (Catalog Snapshot)](#8-layer-15--oracle-context-catalog-snapshot)
9. [Layer 2 — Semantic IR & Symbol Resolution](#9-layer-2--semantic-ir--symbol-resolution)
10. [Layer 2 — Dependency Graph Builder](#10-layer-2--dependency-graph-builder)
10A. [Layer 2.5 — Analysis Orchestration](#10a-layer-25--analysis-orchestration)
11. [Layer 3 — Documentation Generator](#11-layer-3--documentation-generator)
12. [Layer 3 — Static Analysis (SAST)](#12-layer-3--static-analysis-sast)
13. [Layer 3 — Bindings Generator](#13-layer-3--bindings-generator)
13A. [External MCP Integration (oraclemcp)](#13a-external-mcp-integration-oraclemcp)
14. [Layer 4 — Lineage Engine](#14-layer-4--lineage-engine)
15. [Layer 5 — CI/CD Recompilation Cascade](#15-layer-5--cicd-recompilation-cascade)
16. [Out of scope — Referential-Integrity Subsetting (separate future plan)](#16-out-of-scope--referential-integrity-subsetting-separate-future-plan)
17. [Oracle-specific semantic hazards](#17-oracle-specific-semantic-hazards)
18. [Cross-cutting concerns](#18-cross-cutting-concerns)
19. [Test corpus strategy](#19-test-corpus-strategy)
20. [Distribution & packaging](#20-distribution--packaging)
21. [Licensing strategy](#21-licensing-strategy)
22. [Verification standards](#22-verification-standards)
23. [Open decisions (D-decisions)](#23-open-decisions)
24. [Risks](#24-risks)
25. [Bead transfer plan](#25-bead-transfer-plan)
26. [Glossary](#26-glossary)
27. [Reference assets](#27-reference-assets)
28. [Status / Version log](#28-status-log)

---

## 0. Document conventions

- **Layers** are architectural strata. Lower layers are dependencies of higher layers. Layer N may only depend on Layers 0..N-1.
- **Components** live within layers. Independent components in the same layer may be built concurrently.
- **Rule identifiers:** `R<n>`. Rules are project-wide constraints, equally binding on every component.
- **Decision identifiers:** `D<n>`. Decisions are explicit choices the founder makes (sometimes deferred). Each D-decision has options, tradeoffs, and a recommendation.
- **Bead seeds:** `PLSQL-<COMPONENT>-<###>`. Each seed is a self-contained unit of work with explicit acceptance criteria, dependencies on other seeds, and an effort tag (S = ≤1 swarm-day, M = ≤1 swarm-week, L = >1 swarm-week, XL = needs decomposition).
- **No timelines.** No "Phase 1," "Q3 2026," "first wave." Work proceeds along the dependency graph. Cadence is implicit in the graph + swarm capacity, not pre-committed.
- **Status flags:** `[OPEN]` (needs founder decision), `[FUTURE-PLAN]` (outside this complete-release plan; requires a separate plan), `[OUT-OF-SCOPE]` (explicitly excluded), `[CLOSED]` (decided).
- **Glossary** at §26 for every domain term that appears more than once.

---

## 1. Identity

### 1.1 Purpose

Build a hardened PL/SQL parser, an offline-first Oracle catalog model, and the suite of downstream Oracle code-intelligence products they enable. The parser + catalog + dependency graph are the load-bearing assets; multiple products consume them. **The first release ships the full working product**: parser + project loader + catalog + engine orchestrator + semantic IR + symbols + privileges + embedded-SQL semantics + dependency graph + lineage + SAST + docs + bindings + CI/CD recompilation cascade. All of these are in scope of this plan and converge together; there are no intermediate alpha/beta releases. Subsetting (§16) is the one component routed to a separate future plan because it has its own competitive landscape and complexity. Each in-scope product addresses a documented market gap (see `initial-ideas.md` for evidence and competitive landscape). All products share one parser, one symbol resolver, one privilege model, one dependency graph builder — a single technical investment yields a multi-product portfolio that ships together.

### 1.2 Why this project, why now

Multiple market signals converge:

- **Oracle lineage tooling exists, but the public surfaces are narrower than this plan's target.** IBM acquired Manta on 2023-10-24. Atlan's Oracle lineage flow is centered on crawled metadata plus an Oracle Miner that extracts query history from AWR snapshots. Collibra documents Oracle SQL lineage and represents procedures/packages as business-logic containers, while also calling out JDBC harvesting limits such as missing CTAS lineage unless SQL text is supplied separately. Alation added stored-procedure lineage on selected connectors in 2024.3.3, but Oracle is not on the published supported-connector list for that feature. The gap is not "nobody supports Oracle"; the gap is offline, package-aware PL/SQL semantics with explicit uncertainty accounting and recompile planning.
- **PL/SQL SAST is occupied but fragmented.** SonarQube offers commercial PL/SQL analysis with optional data-dictionary lookup; Veracode scans packaged PL/SQL source up to Oracle 21c and earlier; ZPA remains a useful reference implementation. There is still room for a Rust-native CLI that treats catalog-awareness, SARIF, dynamic-SQL evidence, and lineage integration as first-class.
- **PL/SQL → Rust/Go/TS type-safe bindings** do not exist in any commercial or popular OSS form. Every existing transpiler targets Java, Python, or T-SQL.
- **No first-party Oracle documentation generator** has been maintained in over a decade (PLDoc effectively dead).
- **Oracle itself validated MCP demand.** SQLcl now ships an official MCP server with 6 documented tools plus restrict-level and audit features, and Oracle is actively extending it. That validates the workflow category, but the current surface remains centered on connection management and raw SQL/SQLcl execution rather than package-aware semantic workflows.
- **Liquibase Secure** was repositioned in November 2025 around database-layer AI governance, but its public framing still treats Oracle primarily as a SQL-dialect deployment target, not as a packaged-procedural dependency system. The PL/SQL recompilation cascade remains uncovered.
- **Tonic.ai and Delphix** sell subsetting at enterprise prices but explicitly do not handle Oracle package dependencies.

The shared technical blocker — a high-quality PL/SQL parser with symbol resolution and a dependency graph — has prevented all of these from being unified by one vendor. The founder has the technical depth, the swarm capacity for 24/7 agent-driven implementation, and a permissively licensed starting grammar (ANTLR grammars-v4, BSD-3) to make the investment pay back across six products.

These market assertions are intentionally tied to a 2026-05-12 doc review. README, homepage, sales copy, and launch collateral must re-check them before publication.

### 1.3 Architectural seed

There is no existing seed. This is a green-field Rust workspace. The closest reference projects in the founder's portfolio are XEngine (computation kernel pattern) and `oracle-mcp` (Oracle access pattern), neither of which contributes code directly but both of which inform conventions on async runtime, error handling, and binary distribution.

### 1.4 Commercial nucleus

The plan covers six product surfaces (lineage, SAST, docs, bindgen, CI/CD recompile cascade, and the foundation engine). The **commercial nucleus** — the one paid story the founder leads with, the homepage headline, the buyer's purchase justification — is:

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

The paid product is **Oracle Change Impact + Recompile Assurance**, composed of:

- lineage + `what-breaks`
- semantic change classification + `compare-oracle-deps`
- recompile order + dependency-aware DDL ordering
- CI/CD `predict` / `plan` / `gate` / isolated-target `verify`
- evidence-bearing reports with the Trust Block (§1.5)

Other product surfaces remain in the plan and ship at GA, but they are not equal in the GTM story:

| Surface | Role |
|---------|------|
| Parser / catalog / IR / facts / depgraph | Foundation and credibility layer |
| Lineage + CI/CD cascade | **Commercial nucleus — what's sold** |
| Docs generator | Adoption surface; comprehension and onboarding |
| SAST | Audit / security appendix; SARIF integration to existing toolchains |
| Bindings generator | Developer-love wedge for Rust teams; not the primary enterprise budget driver |

**Why this exists.** Buyers do not buy "one parser feeding six surfaces." Buyers buy a painful outcome solved. "What breaks if we deploy this?" is urgent, budgetable, and demonstrable. It connects directly to failed releases, outage avoidance, DBA approval, and audit evidence, and it uses the hardest parts of the engine. That strengthens defensibility against horizontal catalog incumbents whose public Oracle lineage surfaces remain centered on metadata, query history, or selected stored-procedure views rather than offline package semantics, uncertainty accounting, and recompile planning.

**SKU framing.** The release SKU shape is three tiers; the *commercial GA* (D19) is the paid tiers shipping together as one product.

| Tier | License | Contents | Pricing band |
|------|---------|----------|--------------|
| Foundation OSS | Apache-2.0 OR MIT (per §21) | parser, project loader, catalog snapshot, semantic IR, symbols, privileges, sqlsem, flow, facts, depgraph, engine, bindgen, doc generator, SAST, CLI surfaces (`plsql`, `plsql-depgraph`, `usr-loop`) | Free |
| Change Impact Pro | Apache-2.0 OR MIT (per §21) | lineage + `what-breaks` + semantic change classification + dynamic-SQL evidence + HTML/PDF change-approval reports + orphan-candidates report (§13.8). MCP exposure, when needed, is owned by `oraclemcp` consuming the engine crates (§13A) | Per-estate annual license |
| Release Assurance | Apache-2.0 OR MIT (per §21) | CI/CD gate + recompile plan + isolated-target verify + policy thresholds + PR-integration (§14.7). MCP exposure, when needed, is owned by `oraclemcp` consuming the engine crates (§13A) | Per-estate annual license, may stack with Change Impact Pro |

Pricing band ($20-60k/yr) and exact ladder remain under the Commercial Validation Track (a follow-up amendment); the SKU shape is fixed by this section.

**Hero demo.** Every customer-visible artifact (homepage, design-partner pitch, conference talk, sales deck, README, doc landing page) leads with the same hero scenario:

```
DROP COLUMN customers.legacy_segment
```

The corpus fixture for this scenario lives at `corpus/lab/hero_diff_dropcol/` (PLSQL-LAB-008): the `customers` table with a `legacy_segment` column, three dependent PL/SQL objects (`v_high_value_customers` view, `pkg_customer_report` package body, `proc_segment_summary` procedure), plus a before/after/change.diff/expected_what_breaks.json golden set. The L1 seed corpus in `corpus/lab/l1/` carries the base table and objects. Live Oracle replay for this scenario now belongs in `oraclemcp`; this repo keeps the offline corpus, impact expectation, and engine-side checks.

The report shows: direct + transitive impact, Oracle dictionary cross-check, engine-only dynamic-SQL evidence, uncertain edges with `UnknownReason`, exact-vs-unknown column lineage, recompile order, why production verification must run against an isolated target only. This is the canonical product proof — release blockers (§22) include "the hero scenario renders cleanly on the synthetic lab corpus (§6.2.8.1) with the Trust Block intact."

**Anti-positioning guard.** This section is the standing answer to the question *"are we positioning too close to Liquibase / Flyway?"* No: this tool does not replace deployment orchestrators. It supplies the Oracle-specific semantic impact + recompile intelligence those tools lack. Same for Manta / Atlan / Collibra / Alation: this is not a generic catalog UI; it is the evidence-bearing PL/SQL semantic layer focused on packages, dependency reasoning, and explicit uncertainty reporting.

### 1.5 Evidence UX release gate

The plan's strongest native advantage is that Oracle static analysis cannot be perfect (dynamic SQL, missing catalog metadata, wrapped code, DB-link remote objects, edition-based redefinition, invoker-rights runtime ambiguity) and the engine refuses to hide that under fake green checkmarks. **Completeness, uncertainty, and evidence are not internal correctness mechanisms — they are the central product UX and the brand promise.**

Brand promise: *honest, evidence-bearing Oracle impact intelligence — not perfect, but actionable, auditable, and explicit about what it doesn't know.*

**Every customer-visible report — docs, SAST, lineage, CI/CD — must lead with a compact Trust Block:**

```text
Trust block
- Files parsed cleanly: 94%
- Recovered parses: 5%, Skipped tokens: <1%
- Catalog available: yes (snapshot 2026-05-08T12:00:00Z)
- PL/Scope available: identifiers + statements
- Wrapped units: 3 (UnknownReason::WrappedSource)
- Dynamic SQL sites: 41 total, 7 opaque, 34 with evidence
- DB-link edges: 5 (UnknownReason::DbLinkRemoteObject)
- Missing package bodies: 2 (UnknownReason::MissingPackageBody)
- Exact column lineage: 72%
- Table-scoped unknown column lineage: 19%
- Dynamic unknown column lineage: 9%
- Conditional-compilation branches reachable under this profile: 11 of 14
```

Every important result answers four questions:

1. What do we know?
2. Why do we believe it? (provenance — file, line, parse rule, resolution strategy)
3. What do we not know? (named `UnknownReason`)
4. What would improve confidence? (provide catalog snapshot / enable PL/Scope / add manual row-shape override / add rename mapping / add dynamic-SQL allowlist hints / add value-set hints)

**Hard requirements** (enforced by §22 release gates and §5 GA gate):

- Reports MUST include a Trust Block at the top
- Reports MUST NOT compress completeness into a single "trust score" or "risk score" scalar — a fake scalar recreates the false-certainty problem the plan exists to fix. Specific counts and precision tiers only.
- Every CI gate output MUST support an `unknown budget` policy: thresholds on opaque dynamic SQL, missing catalog metadata, unresolved references; CI fails when the budget is exceeded.
- Every `Unknown` MUST be actionable, not apologetic: pair each unknown with a concrete remediation step.
- Every CLI surface MUST support `--explain-confidence` to drill into the Trust Block.
- HTML report sections MUST partition findings into High / Medium / Low confidence; the customer can hide the low-confidence pane but not by default.
- The `plsql-output` versioned envelope (R5) MUST carry the Trust Block as a first-class field — not an afterthought sidecar.

**This is the moat.** Current alternatives each cover only slices: query-history lineage, selected stored-procedure charts, or file-based SAST packaging. None of their public Oracle surfaces promise offline-first package semantics with explicit `UnknownReason` accounting, Trust Block completeness reporting, dynamic-SQL evidence, and recompile planning in one workflow. This product can win by being more honest and more actionable, and by giving DBAs / governance teams / release engineers / security reviewers something they can attach to audit and change tickets with confidence.

### 1.6 Commercial Validation Track

A pre-commercial-GA paid track for **bounded, productized design-partner engagements** that produce real willingness-to-pay evidence, real buyer language, real referenceable proof, and real corpus exposure without violating the founder constraints. Operationally separate from product release (does not require commercial GA), operationally separate from consulting (fixed scope, fixed deliverable), and operationally separate from open-ended customer development (each engagement is a paid contract, not a "talk to users" session).

The **deliverable** of each engagement is a single artifact: an **Oracle Change Impact Assessment** report for one application schema or one bounded estate slice, generated by the same `AnalysisRun` machinery that drives the commercial-GA product. Report sections:

- Trust Block (§1.5) — completeness profile of the estate
- Dependency + lineage inventory
- `compare-oracle-deps` — engine vs `ALL_DEPENDENCIES` cross-check
- Top dynamic-SQL uncertainty sites with `DynamicSqlEvidence`
- Top 10-20 risky change-impact scenarios identified by the engine
- Package spec/body invalidation and recompile-risk summary
- Orphan-candidates report (§13.8) for the estate, with confidence tiers + AUDIT recommendations
- Catalog / PL/Scope readiness recommendations
- SAST findings appendix (frozen rule pack, high-confidence rules only)
- Remediation pathway: which engine outputs improve once the customer provides which inputs

The report is the same shape the commercial-GA product will emit. The engagement is what gets the report into the hands of paying customers before commercial GA, and what gets real customer code into the development feedback loop via the redacted-repro pipeline (§18.11).

**Commercial shape.** Fixed-fee, fixed-scope, no scope-creep tolerated:

| Field | Value |
|-------|-------|
| Fee | $25k–$40k fixed per engagement (single application schema or bounded estate slice) |
| Conversion incentive | Fee credited 100% against the first annual license if customer converts within 90 days of report delivery |
| Tooling environment | On-premises only. Customer runs the engine binary (foundation-OSS tier) against their own code; no source leaves customer premises unless they explicitly export a strict-redacted support bundle (§18.11). |
| Catalog access | Customer provides a `plsql-catalog` JSON snapshot. Optional PL/Scope outputs improve confidence. No live DB credentials change hands. |
| Duration | 4 weeks from engagement start to report delivery. No "follow-up phase," no "iteration on findings" — feedback rounds become product backlog items, not engagement extensions. |
| Output | Single PDF/HTML report + raw `AnalysisRun` JSON for the customer's own consumption. No source code in the deliverable. |

**Operational guardrails (hard limits enforced by the founder's discipline, not by hope).** These exist because Gemini correctly identified solo-founder consulting drag as the dominant risk; the only way to actually run this program is by treating these limits as non-negotiable:

- **Maximum 2 concurrent engagements.** No exceptions. If a third comes in, it goes on a written waitlist with a quoted delivery date.
- **Maximum 6 total engagements before commercial GA.** This is a hard cap; the program is *validation*, not a business. If the founder is on engagement 7 pre-GA, the strategy has drifted into consulting and must be reset.
- **Warm-intro only.** No cold procurement, no inbound contact form, no LinkedIn outreach. Every engagement comes through a personal introduction from the founder's network (consulting peers, Oracle community, prior colleagues). This filter is what makes 6 engagements survivable.
- **Written "no custom feature work" clause** in every engagement contract. Customer-specific feature requests during the engagement become either: (a) public bead seeds for post-GA roadmap consideration, (b) explicitly rejected with a written note in the engagement file. *Never* shipped as customer-private branches.
- **Standard report template, never bespoke.** Variations are limited to: which sections render given the data quality, and natural per-customer differences in the estate. The structure is identical across engagements. This is how the engagement converges with the GA product instead of diverging from it.
- **On-prem tooling, never SaaS-style hosting.** The founder never holds customer source. The redaction-strict support bundle (§18.11) is the one allowed export path, and it is human-reviewed before any output leaves customer premises.
- **Every manual step that emerges during an engagement becomes either a public bead or an explicit reject in writing.** If something has to be done by hand twice across engagements, it becomes engineering work, not "the founder will keep doing it."
- **Engagement playbook is a public document** (eventually). Once 3-5 engagements have run cleanly, the playbook + report template + ICP qualifier + intake checklist go on the docs site as the canonical "how an assessment works." This sunlight discourages drift into bespoke consulting.

**ICP qualifier.** Not every Oracle shop is a good design partner. Required filters for taking an engagement:

- 200+ PL/SQL objects or 30+ packages (smaller estates produce uninteresting reports)
- Frequent releases or painful release freezes (means the buyer feels the pain)
- Current impact analysis done manually by senior DBAs reading code (the role this product replaces)
- Governance / data-catalog tools already in place but admitting PL/SQL gaps (the role this product augments)
- Willingness to run tooling on-premises and provide a catalog snapshot (procurement / infosec compatibility test)
- Founder has a warm intro to a real decision-maker, not a procurement contact (sales-friction test)

If a prospect fails any of these filters, the engagement is declined. The waitlist is for filtered-and-passed prospects only.

**Risk mitigation against K-risks:**

- **K7 (incumbent response):** real customer assessments produce evidence of what Manta / Atlan / Collibra / Liquibase actually miss in practice on this customer's estate. That evidence becomes the most credible competitive proof the founder can hold.
- **K10 (solo founder commercial bandwidth):** the program is *bounded* (max 6 engagements pre-GA, max 2 concurrent, fixed scope, warm-intro-only) — discipline that converts founder-time into willingness-to-pay evidence without absorbing all of it.
- **K13 (source-only misleading results):** each engagement reveals what catalog metadata customers can actually provide. That feedback shapes `plsql-catalog`'s extraction strategy faster than synthetic corpus alone.
- **K14 (SAST false-positive trust risk):** SAST sits at the appendix of the assessment report, not the headline. The engagement establishes the trust posture for the SAST product before commercial GA.
- **K17 (corpus contamination):** the redacted-repro pipeline (§18.11) is the *only* allowed path from engagement code into the public corpus. Engagement contracts make this an explicit, customer-visible commitment.

**Acceptance criteria (this section, not the engine).**

- Engagement contract template (PDF) committed to `docs/commercial-validation-track/`
- Standard report template (HTML + markdown source) committed to the same directory; the synthetic-lab (§6.2.8.1) hero demo renders against this template
- Intake checklist + ICP qualifier as a written one-pager
- Engagement file structure under a *private* (not committed) operational directory the founder maintains
- After engagement 1: written post-mortem documenting what went well, what scope-creep pressures appeared, and what beads were created from the manual steps
- After engagement 3: public playbook on the docs site

**Bead seeds — Commercial Validation Track.** These are operational beads, not engineering beads, and they live alongside the engineering beads under the `project:plsql-intelligence` label so the founder can track them through the same tooling. Labelled `area:commercial`.

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-CVT-001` | Author standard engagement contract template (PDF + markdown source) including fixed scope, no-custom-feature clause, on-prem-only tooling clause, redacted-repro consent | LIN-021 + LAB-002 | M |
| `PLSQL-CVT-002` | Author standard Change Impact Assessment report template; render against synthetic lab L1 + L2 | CVT-001 + LAB-004 | M |
| `PLSQL-CVT-003` | Author intake checklist + ICP qualifier one-pager | CVT-001 | S |
| `PLSQL-CVT-004` | Author engagement-file structure + operational discipline checklist (private; not committed) | CVT-001 | S |
| `PLSQL-CVT-005` | Engagement 1: founder runs first warm-intro engagement end-to-end | CVT-002 + CVT-003 | XL (operational, not engineering effort) |
| `PLSQL-CVT-006` | Post-engagement-1 written post-mortem; convert manual steps into beads or explicit rejects | CVT-005 | S |
| `PLSQL-CVT-007` | Engagement 2 + 3: validate the playbook converges across customers | CVT-006 | XL (operational) |
| `PLSQL-CVT-008` | Public playbook write-up after engagement 3: blog post + docs-site canonical page | CVT-007 | M |
| `PLSQL-CVT-009` | Engagements 4–6: scale-test the bounded program; identify hard cap signals if scope-creep pressure exceeds discipline | CVT-008 | XL (operational) |
| `PLSQL-CVT-010` | Convert: design-partner customer signs annual license, commercial GA can ship | CVT-009 + GA gate | S (commit moment) |

This is the *one* place in the plan where founder operational discipline is committed in writing. If this track drifts into open-ended consulting, the strategy has failed, and the founder is expected to recognize the drift via the post-mortem cadence and reset.

---

## 2. Scope

### 2.1 In scope

This project covers **Track A** as defined in `initial-ideas.md`: the parser core and every downstream product that consumes it.

| Component | Layer | Purpose |
|-----------|-------|---------|
| Parser Core | 1 | Tolerant parsing of PL/SQL and SQL into lossless CST/token tape + typed AST; ParseBackend-abstracted |
| Project Loader | 1.5 | Repository discovery, SQL\*Plus splitting, `@`/`@@` includes, package spec/body pairing, conditional compilation, wrapped detection |
| Oracle Catalog Snapshot | 1.5 | Offline-first Oracle dictionary metadata (objects, columns, args, synonyms, grants, indexes, constraints, dependencies, scheduler jobs, editioning views, DBMS_METADATA DDL, PL/Scope) from JSON snapshot or stable row ingestion. Live extraction is owned by `oraclemcp` after the offline pivot |
| Analysis Engine | 2.5 | Orchestrates project → parse → catalog → IR → symbols → privileges → sqlsem → flow → facts → depgraph; emits `AnalysisRun` consumed by all product-surface CLIs |
| Semantic IR | 2 | Typed intermediate representation: scopes, declarations, references, control flow, catalog-aware types |
| Symbol Resolver | 2 | Resolve names to declarations across schemas/packages/synonyms with full overload resolution |
| Privileges Model | 2 | Definer/invoker rights, grants, roles, PUBLIC, ACCESSIBLE BY, security-sensitive cross-schema authorizations |
| Embedded-SQL Semantic Model | 2 | Table-alias resolution, projection modeling, CTE/subquery scopes, MERGE source/target, RETURNING INTO, column read/write classification |
| Dependency Graph Builder | 2 | Three-layer node identity (`LogicalObjectId` + `ObjectRevisionId` + optional `PersistentObjectId`); evidence-bearing edges; Oracle dictionary dependency cross-check |
| Lineage Engine | 4 | Cross-object impact graph; diff-aware `what-breaks`; classify-change; SemanticChangeSet |
| Static Analysis Engine | 3 | Rule-based security and quality scanner; precision-tiered rule pack with high-confidence defaults |
| Documentation Generator | 3 | Markdown / static-site documentation with call graphs and table-usage graphs |
| Bindings Generator | 3 | Type-safe Rust bindings (initial target) from PL/SQL package specs and table definitions; sync-first via `OracleExecutor` trait |
| CI/CD Recompilation Cascade | 5 | Pre-deploy invalidation prediction; **isolated-target verify only** (Oracle DDL implicitly commits) |
| USR Loop / Accretion | 5 | Uncertainty-sourced repair loop, privacy-proven fixture generation, sha-pinned gate, append-only ledger, and monotone coverage tripwire |
| External MCP Integration (`oraclemcp`) | external | The MCP server lives outside this repo. `oraclemcp` may depend on the engine library crates behind an optional PL/SQL intelligence feature and owns live Oracle sessions, guarded writes, transport, registry, and distribution (§13A) |
| Referential-Integrity Subsetting | (out of scope) | Routed to a separate future plan; this plan retains a placeholder section + bead seeds for continuity, but the component is NOT part of the first release |

### 2.2 Explicitly out of scope (separate projects)

- **MCP server and live Oracle sessions** — live database connectivity, guarded writes, MCP transport, registry distribution, and production-operations features belong to the separate `oraclemcp` repository. This repo exposes offline engine crates and CLIs; `oraclemcp` may consume them as libraries.
- **First-Responder Kit** — Track C from `initial-ideas.md`. Pure SQL scripts, no parser dependency.
- **Oracle License Scanner** — Track C from `initial-ideas.md`. Pure SQL + rules, no parser dependency.
- **Oracle DBA dashboard, managed Debezium, migration assessment** — not in any track; ruled out by founder.
- **Generation of pure-Rust transpiled PL/SQL bodies** (vs. bindings to call existing PL/SQL): explicit non-goal; the bindings generator wraps Oracle-side execution, it does not translate procedure bodies.

### 2.3 Not in scope of this plan

These are genuine scope exclusions — not "ship later." They belong to other plans or are out of charter entirely. The first release of this plan ships everything in §2.1 simultaneously; it does NOT carve out a subset.

- **Referential-integrity subsetting** — routed to a separate future plan (§16). This plan retains a placeholder section for continuity but the component is not part of the first release.
- **REF cursor projection inference, pipelined-function bindings, and async wrapper backends** — explicit non-goals at first release; the bindings generator emits diagnostics for these and recommends manual implementation. Belongs in a future bindings-extension plan.
- **CI/CD in-place verification on production schemas** — explicit non-goal at any release; the `--dangerously-verify-in-place` guard exists for emergencies, not as a roadmap item (DDL implicitly commits, §15).
- **Customer-defined SAST rule SDK** — internal rule authoring only for the first release (D11).
- **Go and TypeScript bindgen targets** — Rust only at first release (D7).
- **Column-level lineage in non-trivial dynamic SQL** — `Unknown` is the answer at first release (D12).
- **Live workload correlation with AWR/ASH** — static lineage only at first release (D14).
- **Fine-grained incremental semantic re-analysis** — foundation data model supports it (R14); fine-grained invalidation strategy is not implemented at first release (D17).
- **Web UI for the lineage explorer** — captured as a separate project once Lineage Engine ships its CLI + JSON interface.
- **LSP/IDE integration** — `plsql-output` schemas don't preclude it (D20), but no LSP server is built.

---

## 3. Founder constraints

These constraints are non-negotiable for this project. Any work item that would violate one of them is automatically out of scope.

| C# | Constraint | Source |
|----|------------|--------|
| C1 | No ML training of any model on private code/data on founder-owned GPUs. | Session 2026-05-11 |
| C2 | No private code or data passed through founder-owned inference infrastructure. | Session 2026-05-11 |
| C3 | Public foundation models may be called via end-user API keys against end-user data, never against private code for the founder's benefit. | Session 2026-05-11 |
| C4 | No "migration away from Oracle" product positioning — the founder is not in that business. | Session 2026-05-11 |
| C5 | The private PL/SQL corpus is a *pattern reference* — Durak may describe patterns informally to agents so synthetic tests can be authored, but agents may not read private estate source files in service of the product implementation. | Derived from C1+C2 |
| C6 | All artifacts of this project (code, tests, documentation, examples) must be publishable as-is. If a test case must mirror a private estate pattern, it must be re-synthesized from grammar + description, never copied. | Derived from C5 |
| C7 | No commits to anything (CLAUDE.md Rule 1). Agents may stage and reason about changes; only the founder commits. | CLAUDE.md |

---

## 4. Architectural rules

| R# | Rule | Rationale |
|----|------|-----------|
| R1 | Implementation language is **Rust** for all parser-derived components. CLIs are Rust binaries; web/UI is deferred to separate projects. | Performance, single-binary distribution, founder skill, matches `oracle-rs` ecosystem. |
| R2 | The parser core exposes a **backend-independent parsing API**. The first backend candidate is `antlr4rust` + ANTLR grammars-v4 PL/SQL (BSD-3-Clause), but no downstream crate may depend on ANTLR parse-tree types, grammar rule names, or generated-code internals. | The PL/SQL ANTLR grammar is ~10K parser lines + ~2.6K lexer lines with known generation-conflict and exponential-parse-time issues. `antlr4rust` is a third-party runtime, not ANTLR's official core target. Backend abstraction protects every downstream component if antlr4rust proves unworkable. D1 governs first-backend selection; R20 governs isolation. |
| R3 | The project ships as a **single Cargo workspace** with one crate per component. Each component crate is independently publishable. | Allows shared types in `plsql-core`, atomic version bumps, monorepo CI ergonomics. D3 governs workspace shape if R3 proves wrong. |
| R4 | Every component exposes a stable **library API (Rust trait or struct)**, a **CLI binary**, and a **JSON I/O surface** for cross-language integration. CLI and JSON wrap the library — never reverse. | Allows agents, IDE plugins, and CI integrations to consume the same engine without re-wrapping. |
| R5 | All machine-readable outputs use **shared versioned output envelopes from `plsql-output`** (robot-JSON, diagnostics, schema IDs). Component-specific rendering lives in the component crate using shared low-level helpers from `plsql-render` (HTML shell, Markdown helpers, SVG helpers). No component may invent its own robot-JSON envelope or diagnostic shape. | Avoids the god-crate failure mode where one render crate must know `DepGraph` + `ScanResults` + `DocSet` + `BindingPlan` + `LineageResult`. Lower coupling, cleaner versioning, easier to evolve format-specific quirks (SARIF, JUnit, doc HTML). |
| R6 | Test corpora are committed in-tree under `corpus/{public,synthetic,golden,adversarial,db-fixtures}/`. **No private estate code, ever, under any subdirectory.** | C5, C6. |
| R7 | Runtime model: the offline engine is **sync-first**. Public library APIs for parse, IR, depgraph, lineage, SAST, docs, bindgen, CI/CD prediction, catalog snapshot ingestion, and local analysis stay synchronous by default. Do not introduce live Oracle sockets, MCP serving, telemetry, or daemon/network runtime dependencies in this repo. Live Oracle I/O and MCP serving belong in `oraclemcp`; this repo exposes stable library crates and CLIs for that consumer. | Offline analysis workflows stay simple, deterministic, and stable-channel. Async/runtime complexity belongs at the live I/O boundary in the external MCP host, not inside the offline engine. |
| R8 | Error reporting uses **miette** for human-facing diagnostics with source spans. **thiserror** for library errors. No anyhow except in `main()`. | Diagnostic-grade error messages are a product feature, not an afterthought. |
| R9 | Observability uses **tracing** with structured fields. Every public API call emits a span. Performance-sensitive hot paths use `tracing::trace!` not `info!`. | Diagnose customer issues by reading their trace dumps, not by guessing. |
| R10 | Every component ships with a **`--robot-json` flag** that emits machine-parseable output suitable for AI agents. Human-readable output is the default. | Agent-friendliness per `agent-ergonomics-and-intuitiveness-maximization-for-cli-tools` skill. |
| R11 | Every component ships with a **`doctor` subcommand** per the `world-class-doctor-mode-for-cli-tools` skill. | Self-healing CLI tools score higher on the agent-ergonomics rubric and reduce support cost. |
| R12 | The dependency graph and lineage outputs include **provenance metadata** for every edge: which source file, which line range, which parse rule, which resolution strategy fired. | Auditability is a product feature for regulated customers; debuggability for us. |
| R13 | **No uncertainty is silently dropped.** Dynamic SQL, wrapped code, missing catalog metadata, DB-link remote objects, parser recovery regions, conditional-compilation branches, edition-based redefinition, invoker-rights runtime ambiguity, and missing package bodies all become explicit `UnknownReason` records with provenance, confidence, and (where applicable) structured evidence. | Customers must trust that we surface unknowns. Silent omission is a credibility-killer in regulated buying. This is a credibility feature, not a defensive hedge. |
| R14 | Persistent analysis state uses a **`plsql-store` abstraction** backed by SQLite for local CLI use. Source files remain normal files. Cached token tapes, parse diagnostics, semantic fragments, catalog snapshots, dependency-graph snapshots, benchmark results, and corpus metadata are content-addressed by hash. Fine-grained incremental semantic re-analysis is deferred; the foundation data model must support it. | The product lives or dies on large customer schemas and CI speed. Even simple hash-based caching changes the feel of the tool and unlocks agent-driven workflows. Per `rust-cli-with-sqlite` skill. |
| R15 | Public APIs are **semver**. Pre-1.0 releases use `0.y.z` with breaking changes in minor bumps explicitly called out in CHANGELOG. | Standard. |
| R16 | License is **Apache-2.0 OR MIT** for the entire workspace. Every crate — parser, project loader, catalog, semantic IR, symbols, privileges, flow/facts, dependency graph, engine, lineage, SAST, CI/CD cascade, doc generator, bindings generator, accretion, and support tooling — is dual-licensed Apache-2.0 OR MIT. The project is fully open source: there is no source-available or commercially-restricted tier (D8, resolved). | A single permissive license maximizes adoption across Oracle shops and keeps the whole engine auditable. Commercial value, where the project pursues it, sits in support, hosting, and design-partner engagements around the open-source code, never in license restriction. |
| R17 | No telemetry by default. Customers may opt in; opt-in payload is documented and minimal. | Trust posture for regulated buyers. |
| R18 | Code style: `rustfmt` with default config + `cargo clippy -- -D warnings` enforced in CI. No exceptions. | Standard. |
| R19 | Test coverage gate: **80% line coverage** on parser core; **70% line coverage** on every other component. Property-based tests (via `proptest`) for grammar invariants. Coverage tracked in CI but not blocking below threshold. | Measurable quality without ratcheting into busywork. |
| R20 | **Parser backend isolation is mandatory.** All parser backends implement `ParseBackend`. Backend choice is a build/runtime option used for benchmarking, fuzzing, and fallback. Generated parser internals (ANTLR parse-tree types, rule names) are private to the backend crate. The public parser surface is our lossless CST/token tape plus typed AST. | Architectural insurance against the single biggest technical risk: that the first-chosen backend stalls. With isolation, replacing the backend is a contained refactor rather than a project-wide rewrite. |

---

## 5. Dependency graph

```
LAYER 0 — FOUNDATIONS
   plsql-core (shared types, UnknownReason, Confidence, AnalysisProfile, CompletenessReport, SymbolInterner, typed IDs)
   plsql-output (versioned envelopes, robot-JSON, diagnostics, RedactionPolicy)
   plsql-render (HTML/Markdown/SVG/GraphML helpers — shared low-level only)
   plsql-store (content-addressed SQLite cache; immutable-artifact + daemon modes)
   corpus + license manifest
   plan-lint (validates this plan's structural integrity)
                          │
                          v
LAYER 1 — FRONTEND
   plsql-parser
   ParseBackend abstraction (R20)
   lossless CST + token tape; typed AST (semantic, not lossless)
                          │
        ┌─────────────────┴──────────────────┐
        v                                    v
LAYER 1.5 — ORACLE CONTEXT
   plsql-project                        plsql-catalog
   (SQL*Plus splitting, includes,       (offline-first DB metadata:
    spec/body pairing, conditional       %TYPE/%ROWTYPE, synonyms,
    compilation, wrapped detection)      overload signatures, grants,
                                         indexes, constraints, triggers)
        │                                    │
        └──────────────────┬─────────────────┘
                           v
LAYER 2 — SEMANTICS
   plsql-ir ──► plsql-symbols ──► plsql-privileges ──► plsql-depgraph
   (typed IR,   (resolution +    (definer/invoker,    (stable node ids,
    embedded     overloads)       grants, roles)       evidence-bearing
    SQL model,                                       edges; consumes
    flow state,                                      normalized facts)
    FactStore
    emission)
                          │
                          v
LAYER 2.5 — ANALYSIS ORCHESTRATION
   plsql-engine
   (canonical AnalysisRequest → AnalysisRun pipeline,
    artifact loading/saving, cache reuse, downstream CLI input contract)
                          │
        ┌─────────────────┼──────────────────┐
        v                 v                  v
LAYER 3 — PRODUCT SURFACES
   plsql-sast             plsql-doc              plsql-bindgen
   (SAST, SARIF,          (Markdown/HTML +       (sync-first Rust bindings,
    baseline)              embedded graphs)       Defaulted<T>, OracleExecutor)
                          │
                          v
LAYER 4 — LINEAGE PRODUCT SURFACE
   plsql-lineage
   (what-breaks, diff-aware classify-change, compare-oracle-deps,
    column-precision tiers, explain)
                          │
                          v
LAYER 5 — CI/CD / REPAIR PRODUCT SURFACES
   plsql-cicd             plsql-accretion        usr-loop
   (predict modes, recompile cascade, lifecycle classifier, explain-lifecycle,
    isolated-target verify only)

FUTURE PRODUCT (separate plan; consumes catalog + lineage)
   plsql-subset
   (FK + trigger + soft-ref subset extraction, real masking required)
```

**Concurrency rules:**

- Layer 0 must finish first. All other layers block on it.
- Layer 1 (parser frontend) blocks Layer 1.5 and Layer 2.
- Within Layer 1.5, `plsql-project` and `plsql-catalog` are mutually independent.
- Layer 2 components have an internal partial order: IR → symbols → privileges → depgraph. The embedded-SQL model, flow-state solver, and normalized `FactStore` emission are modules inside `plsql-ir`, not separate crates. Phase G (`oracle-plsql-converge-0lnu.14`) was the tracked build of the emitted-fact projection boundary over the existing solver.
- Layer 2.5 (`plsql-engine`) cannot be marked complete until every Layer 2 component is complete. Its skeleton (public types, module structure) may be created during Layer 0 scaffolding, but the implementation belongs to Layer 2.5.
- Within Layer 3, all consumers (`plsql-sast`, `plsql-doc`, `plsql-bindgen`) are mutually independent and consume `FactStore` first, falling to raw IR only for component-specific details.
- Layer 4 (`plsql-lineage`) blocks on Layer 2 + Layer 2.5.
- Layer 5 (`plsql-cicd`, `plsql-accretion`, `usr-loop`) blocks on Layer 4 where impact analysis is required and on Layer 2.5 for analysis-run consumption.
- `plsql-subset` is routed to a separate future plan (§16); not in scope here.

**Maximum parallel work surface** at any moment along this graph:

- Layer 0 done → 1 swarm on parser (Layer 1)
- Layer 1 done → 2 swarms on project + catalog (Layer 1.5)
- Layer 1.5 done → up to 6 swarms on Layer 2 partial-order (IR → symbols, privileges, sqlsem → flow → facts → depgraph)
- Layer 2 done → 1 swarm on engine (Layer 2.5) + 3 swarms on SAST / doc / bindgen (Layer 3) in parallel
- Layer 2.5 + Layer 3 stable → 1 swarm on lineage (Layer 4)
- Layer 4 stable → 1 swarm on CI/CD cascade + accretion/USR loop (Layer 5)

Actual swarm count is governed by available agent capacity, not by the plan.

**Dependency ordering is not public release packaging. It is internal convergence control.** A component may be developed behind an internal quality gate, but no public product release is cut until the GA closure bead passes. This plan ships exactly one public release — the full GA product.

**Internal convergence gates** (NOT public releases, NOT customer-facing milestones, NOT MVPs):

| Gate | Purpose | Closes when |
|------|---------|-------------|
| Parser gate | Prevent downstream work from building on an unstable parser | Parse-quality thresholds met (§7.5), no-panic fuzz target, token-tape round-trip stable, backend tournament decision closed |
| Catalog gate | Prevent downstream from depending on an unfinished metadata model | JSON snapshot round-trip, live extraction fixture, capability diagnostics, PL/Scope optional path |
| Semantic gate | Prevent product surfaces from consuming a half-resolved semantic model | Symbol resolution, privilege model, SQL semantic model, value flow, normalized facts, completeness report all green on corpus |
| Graph gate | Prevent lineage/cicd from building on a half-baked graph | Evidence-bearing dependency graph, Oracle dictionary cross-check, `explain` command |
| Product-surface gate | Prevent GA without all in-scope surfaces converging | All Layer 3 + Layer 4 + Layer 5 product surfaces pass their acceptance criteria |
| GA gate | The single public release | All gates above + docs + release + security + license + plan-lint all green |

These are engineering quality checkpoints, not release packaging. They prevent agents from building features on top of unstable foundations. There is exactly one public release; everything else is internal discipline.

---

## 6. Layer 0 — Foundations

### 6.1 Purpose

Establish the Cargo workspace, shared types, the render crate, the test-corpus harness, and the CI scaffolding that every other layer consumes. Nothing in this layer is shippable to customers; everything is foundational.

### 6.2 Components

#### 6.2.1 Workspace (`plsql-intelligence` repo)

Layout:

```
plsql-intelligence/
├── Cargo.toml                 # workspace root
├── Cargo.lock
├── README.md
├── LICENSE-APACHE
├── LICENSE-MIT
├── rust-toolchain.toml
├── .cargo/config.toml
├── .github/workflows/
│   ├── ci.yml
│   ├── release.yml
│   └── corpus-update.yml
├── crates/
│   ├── plsql-core/             # shared types, UnknownReason, Confidence, Evidence
│   ├── plsql-output/           # versioned output envelopes, robot-JSON, diagnostics
│   ├── plsql-render/           # shared low-level helpers only (HTML/MD/SVG)
│   ├── plsql-store/            # SQLite-backed content-addressed cache
│   ├── plsql-project/          # SQL*Plus splitting, includes, spec/body, wrapped detection, CC preprocessing
│   ├── plsql-parser/           # Layer 1 (ParseBackend-abstracted)
│   ├── plsql-catalog/          # Layer 1.5 (Oracle dictionary metadata + PL/Scope, offline-first)
│   ├── plsql-ir/               # Layer 2 (typed IR, embedded SQL model, flow state, FactStore emission)
│   ├── plsql-symbols/          # Layer 2
│   ├── plsql-privileges/       # Layer 2
│   ├── plsql-depgraph/         # Layer 2
│   ├── plsql-engine/           # Layer 2.5 — canonical analysis-pipeline orchestrator (skeleton in Layer 0)
│   ├── plsql-lineage/          # Layer 4 product surface
│   ├── plsql-sast/             # Layer 3 product surface (SAST)
│   ├── plsql-doc/              # Layer 3 product surface
│   ├── plsql-bindgen/          # Layer 3 product surface
│   ├── plsql-cicd/             # Layer 5 product surface
│   ├── plsql-accretion/        # Layer 5 uncertainty-sourced repair loop
│   └── plsql-subset/           # Future product — placeholder only
├── corpus/
│   ├── manifest.toml           # per-file license + provenance entries
│   ├── public/                 # checked-in public PL/SQL samples
│   ├── synthetic/              # agent-generated test cases
│   ├── adversarial/            # fuzz-derived inputs that historically failed
│   ├── db-fixtures/            # installable Oracle schemas with expected catalog / PL/Scope / depgraph outputs
│   ├── golden/                 # golden artifacts for end-to-end tests
│   └── lab/                    # public synthetic Oracle estate: sales demo + self-serve eval + AI-swarm target + regression suite + docs source (§6.2.8.1)
├── docs/
│   ├── architecture.md
│   ├── parser-design.md
│   └── components/*.md
└── tools/
    ├── corpus-bench/           # parser benchmark harness
    ├── corpus-grow/            # synthetic test generator
    ├── corpus-license-check/   # CI gate: every public/ file must have a manifest entry
    ├── plan-lint/              # CI gate: validates plan.md structure (heading numbers, anchors, bead IDs, banned wedge language, component coverage matrix). Whitelists quoted historical changelog blocks for banned-language scanning.
    └── usr-loop/               # agent-friendly uncertainty repair loop
```

#### 6.2.2 `plsql-core` crate

Shared types used by every other crate. Public surface:

- `FileId`, `Span`, `Position` — source positions
- `Severity` — Info / Warn / Error / Fatal
- `Diagnostic` — miette-compatible diagnostic shape
- `JsonExportable` trait — marker for types that round-trip through JSON
- `RobotJson` — wrapper for `--robot-json` output
- `UnknownReason` — canonical taxonomy for incomplete analysis:
  ```rust
  pub enum UnknownReason {
      DynamicSqlOpaque,
      DbLinkRemoteObject,
      WrappedSource,
      MissingCatalogObject,
      MissingPackageBody,
      ConditionalCompilationBranch,
      EditionedObject,
      InvokerRightsRuntimeResolution,
      RuntimeGrantOrRole,
      UnsupportedDialectFeature,
      ParserRecoveryRegion,
  }
  ```
- `Confidence` — shared confidence type with bands (High/Medium/Low/Opaque) and explanations
- `Evidence` — structured "why we believe this is true" record attached to inferences
- `AnalysisProfile` — canonical environment profile for one analysis run:
  ```rust
  pub struct AnalysisProfile {
      pub oracle_version: OracleVersion,          // 11g, 12c, 19c, 21c, 23ai, 26ai
      pub compatibility: Option<OracleVersion>,
      pub feature_policy: FeaturePolicy,           // version-gated feature registry
      pub current_schema: Option<SchemaName>,
      pub current_user: Option<UserName>,
      pub current_edition: Option<EditionName>,
      pub plsql_ccflags: HashMap<String, LiteralValue>,
      pub nls: NlsSettings,
      pub enabled_roles: Vec<RoleName>,
      pub db_link_policy: DbLinkPolicy,
  }

  pub struct FeaturePolicy {
      pub enabled: BTreeSet<OracleFeature>,
      pub disabled: BTreeSet<OracleFeature>,
      pub unknown_feature_behavior: UnknownFeatureBehavior,
  }

  pub enum OracleFeature {
      SqlBoolean23ai,
      PlsqlVector23ai,
      BinaryVector26ai,
      SparseVector26ai,
      VectorArithmetic26ai,
      PackageResettable26ai,
      JsonRelationalDuality23ai,
      SqlMacros,
      PolymorphicTableFunctions,
      MultilingualEngineCallSpecs,
  }
  ```
  Replaces scattered version checks across the codebase. Every analysis run records its profile so artifacts are reproducible. Lets the engine ask `profile.feature_policy.enabled.contains(&OracleFeature::SqlBoolean23ai)` rather than reasoning ad-hoc about Oracle versions.
- `CompletenessReport` — analysis coverage + blind-spot summary, emitted by every `AnalysisRun`:
  ```rust
  pub struct CompletenessReport {
      pub files_total: usize,
      pub files_parsed_cleanly: usize,
      pub files_recovered: usize,
      pub skipped_token_ratio: f32,
      pub objects_total: usize,
      pub objects_with_source: usize,
      pub objects_catalog_only: usize,
      pub wrapped_units: usize,
      pub missing_package_bodies: usize,
      pub dynamic_sql_sites: usize,
      pub opaque_dynamic_sql_sites: usize,
      pub db_link_edges: usize,
      pub unresolved_references: usize,
      pub catalog_available: bool,
      pub plscope_available: bool,
  }
  ```

#### 6.2.3 `plsql-output` crate

Versioned output envelopes consumed by every component:

- `RobotJsonEnvelope<T>` — schema-versioned JSON envelope used by every `--robot-json` output; format-id + schema-version + payload
- `DiagnosticEnvelope` — canonical diagnostic shape (wraps `plsql-core::Diagnostic`) used by every component
- `EvidenceEnvelope` — canonical structured-evidence shape for low-confidence inferences
- `RedactionPolicy` — shared policy applied before any report/export leaves the process (see §18.11)
- Schema IDs registered in a single `OUTPUT_SCHEMAS` const so consumers can pin versions
- Output schemas intentionally aligned with future LSP/IDE consumer use cases: diagnostics, document symbols, references, definitions, call hierarchy, hover text (see D20)

No component invents its own robot-JSON envelope or diagnostic shape (R5). When format compatibility needs to evolve, the envelope bumps `schema_version`.

#### 6.2.4 `plsql-render` crate

**Low-level rendering helpers only** — not a god crate. Public surface:

- `html::shell(title, body) -> String` — common HTML skeleton with theme hooks
- `markdown::table(headers, rows) -> String`
- `svg::node_graph(graph: &impl GraphView) -> String` — generic SVG renderer over a `GraphView` trait that components implement
- Format-specific helpers for HTML, Markdown, SVG only

Component crates own their domain-specific output (SARIF in `plsql-sast`, doc HTML in `plsql-doc`, lineage HTML in `plsql-lineage`, GraphML in `plsql-depgraph`). They use `plsql-render` helpers for the boring parts.

#### 6.2.5 `plsql-engine` crate **(Layer 2.5 — implementation; Layer 0 — skeleton only)**

**Canonical orchestration layer** for complete analysis runs. Wires project loading, parsing, optional catalog loading + PL/Scope, semantic analysis, symbol resolution, privilege modeling, embedded-SQL semantics, value flow, normalized facts, dependency-graph construction, and cache reuse into one reproducible pipeline. This is **not** a god crate — it does not implement analysis logic, only sequences and parameterizes the existing crates.

**Architectural placement:** the crate skeleton and public type contracts (`AnalysisRequest`, `AnalysisRun`, etc.) are created during Layer 0 scaffolding so consumer crates can compile against them. The **implementation** belongs to Layer 2.5 and must not be marked complete until parser, project, catalog, IR, symbols, privileges, SQL semantics, flow, facts, and depgraph are all complete. The v0.3 / v0.4 plan had this in Layer 0 as both skeleton and implementation — that was an architectural bug (Layer 0 cannot finish first if it contains a crate that depends on every other layer).

Public API:

```rust
pub fn analyze_project(req: AnalysisRequest) -> Result<AnalysisRun, EngineError>;

pub struct AnalysisRequest {
    pub project_root: PathBuf,
    pub analysis_profile: AnalysisProfile,
    pub parser_backend: ParserBackendChoice,
    pub catalog_source: CatalogSourceConfig,
    pub cache: CacheConfig,
    pub redaction_policy: RedactionPolicy,
}

pub struct AnalysisRun {
    pub run_id: AnalysisRunId,
    pub profile: AnalysisProfile,
    pub project: ProjectModel,
    pub parse_results: Vec<ParseResult>,
    pub catalog: Option<CatalogSnapshot>,
    pub semantic_model: SemanticModel,
    pub sql_semantic: SqlSemanticModel,
    pub flow_summary: FlowSummary,           // value flow / taint / value sets
    pub fact_store: FactStoreSnapshot,        // canonical fact-store reference for product surfaces
    pub dep_graph: DepGraph,
    pub completeness: CompletenessReport,
    pub diagnostics: Vec<Diagnostic>,
    pub artifacts: AnalysisArtifactManifest,  // schema version, content hashes, redaction policy state
}
```

All product-surface CLIs (`plsql-sast`, `plsql-doc`, `plsql-bindgen`, `plsql-lineage`, `plsql-cicd`, `plsql-accretion`, `usr-loop`) consume `AnalysisRun` or its persisted artifact contract, not ad-hoc combinations of lower-layer APIs. This prevents architectural drift where each consumer composes the lower crates slightly differently — which would yield divergent name-resolution results across SAST, lineage, docs, release gates, and repair loops over time.

The `plsql analyze` umbrella command produces an `AnalysisRun` once; downstream commands take it as input. This enables the workflow: "run `plsql analyze`, then ask lineage / SAST / docs questions against the same run."

#### 6.2.6 `plsql-store` crate

SQLite-backed local content-addressed cache for:

- source file hashes
- token tapes
- parse diagnostics
- semantic fragments
- catalog snapshots
- dependency graph snapshots
- benchmark / corpus metadata

The store is **optional** for library users and **mandatory** for large CLI workflows. Source files remain normal files; only derived artifacts are content-addressed. Cache invalidation is by hash + a strategy registry that names which derived artifacts depend on which inputs.

Two access modes:

- **Immutable artifact mode** for CI and reproducibility — `AnalysisRun` artifacts are written once and treated as immutable by downstream readers
- **Local daemon mode** (`plsqld`) for fast repeated developer queries — keeps a warm cache, never phones home, no network telemetry, explicit cache directory. CI should always prefer immutable artifacts over daemon state.

#### 6.2.7 `plsql-project` crate

Turns a repository or exported schema directory into a normalized project model. Architecturally this is Layer 1.5 input normalization, but the crate is created during Layer 0 scaffolding because it has no parser dependency and unblocks every subsequent layer.

Responsibilities:

- File discovery and glob handling
- SQL\*Plus statement splitting (`/`, `@`, `@@`, `PROMPT`, `SET`, substitution variables)
- `@` / `@@` include tracking and recursion
- Package spec/body pairing
- Wrapped-source detection (`WRAPPED` keyword, encoded body)
- **Conditional-compilation preprocessing** using `AnalysisProfile::plsql_ccflags`. First implementation emits a selected-source view plus inactive-region provenance — the parser parses what Oracle would compile, not the un-preprocessed text.
- Source provenance manifest

Public API:

```rust
pub fn load_project(root: &Path, config: ProjectConfig) -> ProjectModel;

pub struct ProjectModel {
    pub files: Vec<SourceFile>,
    pub preprocessed_files: Vec<PreprocessedSourceFile>,
    pub scripts: Vec<ScriptUnit>,
    pub includes: Vec<IncludeEdge>,
    pub conditional_flags: Vec<ConditionalFlag>,
    pub inactive_regions: Vec<InactiveConditionalRegion>,
    pub spec_body_pairs: Vec<SpecBodyPair>,
    pub wrapped: Vec<WrappedSource>,
    pub diagnostics: Vec<Diagnostic>,
}
```

A future **variant-analysis mode** can parse all feasible conditional branches and report branch-specific edges — useful for libraries that ship with multiple `PLSQL_CCFLAGS` configurations. Not in first close.

#### 6.2.8 `corpus/` test infrastructure

Sub-directories:

- `corpus/public/` — committed public PL/SQL samples (Oracle HR/OE/SH/PM/IX/BI sample schemas, public APEX source, antlr/grammars-v4 PL/SQL test cases, well-known OSS PL/SQL projects with permissive licenses). **Every file must have a manifest entry** (see below).
- `corpus/synthetic/` — agent-generated test cases authored from grammar + pattern descriptions. Every file carries a header comment naming the pattern it exercises.
- `corpus/adversarial/` — fuzz-derived and regression inputs that historically caused parser or analyzer failures. Cargo-fuzz seeds from here.
- `corpus/db-fixtures/` — installable Oracle schemas with expected catalog / PL/Scope / depgraph outputs (full spec in §19.6).
- `corpus/golden/` — golden artifacts (expected JSON output for end-to-end tests). Regenerated via `cargo run --bin corpus-update` after deliberate behavior changes.
- `corpus/lab/` — **the public synthetic Oracle estate that doubles as the product's demo, sales, and self-serve evaluation artifact** (full spec in §6.2.8.1 below; not just test data — a first-class deliverable).
- `corpus/manifest.toml` — per-file licensing and provenance discipline. Every committed file under `corpus/public/` MUST have an entry:
  ```toml
  [[file]]
  path = "public/oracle-samples/hr/create.sql"
  source_url = "https://github.com/oracle-samples/db-sample-schemas"
  license = "UPL-1.0"
  redistribution_allowed = true
  fetched_on = "2026-05-11"
  notes = "Oracle HR sample schema, vendored verbatim"
  ```
  Files without redistribution permission are referenced by URL but never vendored. A CI gate (`tools/corpus-license-check/`) blocks PRs that add files without manifest entries.

#### 6.2.8.1 `corpus/lab/` — self-serve evaluation kit

The lab is a public, fully synthetic, Oracle-style PL/SQL estate that serves five jobs at once: **sales demo, self-serve prospect evaluation, AI-swarm integration target, end-to-end regression suite, documentation source**. It must feel like a real long-lived Oracle application — not a toy. No private estate code, no customer-derived patterns; everything synthesized from grammar + design under C5/C6.

**Layered build plan.** Build in size-tiered increments so the lab is useful early and credible later. Each layer must include the hazards listed before the next layer starts.

| Layer | Package count | Mandatory hazards (cumulative) |
|-------|---------------|-------------------------------|
| Seed (L1) | 10 packages + 5 views + 2 triggers | basic spec/body pairs, %TYPE, %ROWTYPE, overloads, one synonym, one DBMS_OUTPUT |
| Working (L2) | 30 packages + 15 views + 8 triggers + 4 scheduler jobs + 1 editioning view | + private/public synonyms, ACCESSIBLE BY, definer/invoker rights mix, package state, deterministic vs default behavior, EXECUTE IMMEDIATE with concatenation, EXECUTE IMMEDIATE with bind variables, DBMS_ASSERT usage |
| Realistic (L3) | 75+ packages + 30+ views + 15+ triggers + ~10 scheduler jobs | + DB-link references (resolvable to a second synthetic schema), wrapped unit (`UnknownReason::WrappedSource`), missing package body, conditional-compilation `$IF`/`$$plsql_ccflags`, autonomous transactions, RETURNING INTO, MERGE source/target with overlapping projections, edition-based redefinition, REF cursor opaque region, opaque dynamic SQL with no recoverable evidence (negative case) |

L3 is the GA release shape (referenced in §22 release gates). L1 and L2 unblock earlier demos and earlier internal acceptance work.

**Required artifacts shipped alongside the lab:**

- `corpus/lab/sample_billing_synthetic/` — primary schema. Domain: telecom-style billing (synthesized, generic — no private estate patterns). Drives the hero demo (§1.4).
- `corpus/lab/sample_governance_synthetic/` — secondary schema, smaller, used for cross-schema synonym + DB-link scenarios and for the `compare-oracle-deps` demo.
- `corpus/lab/snapshots/` — pre-computed Oracle catalog JSON snapshots produced by `plsql-catalog` against an Oracle XE 23ai install of the lab schema. Committed so the no-database path works.
- `corpus/lab/plscope/` — pre-computed PL/Scope outputs for the same snapshots, so symbol-resolution differential testing (§20.4) works without a running database.
- `corpus/lab/expected/` — golden expected outputs for every product surface (parse diagnostics, depgraph, what-breaks for the hero scenario, SAST findings on a frozen rule pack, doc HTML, bindgen Rust output, CI gate report, orphan-candidates report). Regenerated only on deliberate behavior changes.
- `corpus/lab/diffs/` — canned proposed-change diffs that drive the demo paths (DROP COLUMN scenario, package-spec signature change, table type widening, scheduler-job removal, dynamic-SQL allowlist addition).
- `corpus/lab/oracle-xe-install/` — SQL scripts that install the lab into a fresh Oracle XE 23ai container in under 60 seconds. Used by `make demo-oracle-xe`.

**Required `make` targets** (and equivalents in `cargo xtask`):

- `make demo-no-db` — runs the hero `what-breaks` demo against the committed snapshot, no Oracle install needed. Output: `expected/what-breaks.html` is regenerated and diff'd against the committed golden.
- `make demo-oracle-xe` — boots Oracle XE 23ai in a container, installs the lab schema, runs the full pipeline including live catalog extraction and live `compare-oracle-deps` against `ALL_DEPENDENCIES`.
- `make demo-all-personas` — runs persona-specific demo scripts and emits the artifact set each persona is supposed to see (release-engineering lead, senior DBA, security reviewer, data-governance owner, Rust dev integrating bindings).
- `make demo-record` — drives `vhs` / similar tooling to record terminal sessions for the README and the marketing site without leaking customer data.

**Public CI runs the lab on every PR.** The lab acceptance criteria are part of the §22 release gate; drift in any of the `corpus/lab/expected/` artifacts blocks merge unless explicitly updated. This makes the lab the cheapest, fastest signal that a behavioral change has shipped in any product surface.

**Anti-patterns explicitly avoided:**

- The lab is not configurable, not extensible, not a second product. It exists to prove and demo the engine, not to be the engine.
- The lab does not gradually become "the engine's standard library." Anything that becomes load-bearing graduates to `corpus/public/` with a real provenance manifest entry, or to one of the engine crates.
- The lab is not a beautiful customer-facing OSS project on its own. It is a sales/eval/test artifact owned by this plan, deliberately ugly where realism requires it (legacy naming, surprising overloads, inconsistent error handling, edition-of-package-state inconsistencies).

**Bead seeds — Lab.** Layer 0 ships L1 (seed). L2 lands during the Semantic / Graph convergence gates. L3 is a GA release blocker.

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-LAB-001` | L1 seed: 10 synthetic packages + 5 views + 2 triggers + manifest | WS-011 | M |
| `PLSQL-LAB-002` | L1 hero diff + expected `what-breaks` golden artifact | LAB-001 + lineage skeleton | M |
| `PLSQL-LAB-003` | `make demo-no-db` target + CI integration | LAB-002 | S |
| `PLSQL-LAB-004` | L2 expansion: synonyms, ACCESSIBLE BY, rights mix, DBMS_ASSERT scenarios + EXECUTE IMMEDIATE with/without binds | LAB-001 | L |
| `PLSQL-LAB-005` | `corpus/lab/snapshots/` + `corpus/lab/plscope/` pre-computed artifacts | LAB-004 + catalog gate | M |
| `PLSQL-LAB-006` | L3 realism: DB-link cross-schema, wrapped unit, missing body, $IF, autonomous tx, edition-based redefinition, opaque dynamic SQL | LAB-005 | L |
| `PLSQL-LAB-007` | Oracle XE 23ai container install scripts + `make demo-oracle-xe` | LAB-006 | M |
| `PLSQL-LAB-008` | Persona-specific demo scripts (release eng / DBA / security / governance / Rust dev) | LAB-007 | M |
| `PLSQL-LAB-009` | `make demo-record` VHS terminal-recording integration | LAB-008 | S |
| `PLSQL-LAB-010` | Lab-as-release-gate wiring in §22 + PR-blocking CI for `corpus/lab/expected/` drift | LAB-009 | M |

#### 6.2.5 CI scaffolding

- `ci.yml` — runs `cargo fmt --check`, `cargo clippy -- -D warnings`, `cargo test --workspace`, `cargo bench --no-run`, corpus parse-success rate check, golden artifact diff.
- `release.yml` — triggered on tag; runs full test suite + builds prebuilt binaries for Linux x86_64, macOS aarch64, Windows x86_64 + publishes to crates.io and GitHub Releases.
- `corpus-update.yml` — weekly cron; pulls new public corpus, re-runs synthetic generator, files a PR if anything new fails to parse.

### 6.3 Acceptance criteria

- Workspace compiles cleanly with `cargo build --workspace --release` on Linux, macOS, Windows.
- `cargo clippy -- -D warnings` passes on every crate.
- `cargo fmt --check` passes.
- `cargo test --workspace` runs the test scaffolding (no tests yet at this layer; verifies harness wiring).
- `plsql-output` round-trips a trivial value through `RobotJsonEnvelope` with stable schema-id and version.
- `plsql-render` helpers render trivial HTML/Markdown/SVG correctly.
- `plsql-store` opens a fresh SQLite cache and round-trips a content-addressed blob.
- `plsql-project` loads a sample script directory, splits SQL\*Plus statements, and identifies spec/body pairs on a synthetic 5-file project.
- `corpus/manifest.toml` populated; `tools/corpus-license-check/` passes.
- CI pipeline green on a fresh PR.
- `corpus/public/` populated with at least 20 publicly-licensed PL/SQL files, every one of them having a manifest entry.
- `LICENSE-APACHE` and `LICENSE-MIT` present at repo root.

### 6.4 Bead seeds — Layer 0

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-WS-001` | Initialize Cargo workspace + license files + README skeleton | none | S |
| `PLSQL-WS-002` | Wire `rust-toolchain.toml`, `.cargo/config.toml`, `rustfmt.toml`, `clippy.toml` | WS-001 | S |
| `PLSQL-WS-003` | Author `plsql-core` shared types: `FileId`, `Span`, `Position`, `Severity`, `Diagnostic`, `UnknownReason`, `Confidence`, `Evidence` | WS-002 | M |
| `PLSQL-WS-004` | Author `plsql-output` crate: `RobotJsonEnvelope<T>`, `DiagnosticEnvelope`, `EvidenceEnvelope`, schema-version registry | WS-003 | M |
| `PLSQL-WS-005` | Author `plsql-render` low-level helpers: `html::shell`, `markdown::table`, `svg::node_graph` (over generic `GraphView` trait) | WS-003 | M |
| `PLSQL-WS-006` | Author `plsql-store` crate: SQLite schema for content-addressed cache + `cache_strategy` registry | WS-003 | M |
| `PLSQL-WS-007` | Author `plsql-project` crate: file discovery + manifest model | WS-003 | M |
| `PLSQL-WS-008` | Implement `plsql-project` SQL\*Plus-aware statement splitter (`/`, `@`, `@@`, `PROMPT`, `SET`, substitution variables) | WS-007 | M |
| `PLSQL-WS-009` | Implement `plsql-project` package spec/body pair detection + wrapped-source detection | WS-007 | S |
| `PLSQL-WS-010` | Implement `plsql-project` conditional-compilation **preprocessor**: selected-source view + inactive-region provenance, parameterized by `AnalysisProfile::plsql_ccflags` | WS-008 | L |
| `PLSQL-WS-010A` | Add variant-analysis mode: parse all feasible conditional branches and report branch-specific edges (deferred from first close) | WS-010 | L |
| `PLSQL-WS-011` | Author `corpus/` directory structure + `corpus/manifest.toml` schema | WS-002 | S |
| `PLSQL-WS-012` | Ingest Oracle HR / OE / SH sample schemas into `corpus/public/` with manifest entries | WS-011 | S |
| `PLSQL-WS-013` | Ingest antlr/grammars-v4 PL/SQL test corpus into `corpus/public/` (BSD-3) with manifest entries | WS-011 | S |
| `PLSQL-WS-014` | Author `tools/corpus-license-check/` — CI gate that fails PRs adding files without manifest entries | WS-011 | M |
| `PLSQL-WS-015` | Wire `ci.yml` — fmt, clippy, test, parse-success rate check, corpus-license-check | WS-002 + WS-014 | M |
| `PLSQL-WS-016` | Wire `release.yml` — tagged-release cross-platform binary build | WS-015 | M |
| `PLSQL-WS-017` | Document architecture at `docs/architecture.md` (300+ lines, references this plan) | WS-001 | M |
| `PLSQL-ENG-000` | **Layer 0 skeleton only:** create `plsql-engine` crate skeleton + public module structure with type stubs so consumer crates can compile against the contracts. Implementation beads ENG-001..005 live in §10A.3 (Layer 2.5) | WS-003 | S |
| `PLSQL-CORE-IDS-001` | Implement typed-ID/newtype pattern + `SymbolInterner` in `plsql-core` | WS-003 | M |
| `PLSQL-SUPPORT-001` | Implement support-bundle exporter with strict redaction manifest | WS-006 + WS-004 | M |
| `PLSQL-SUPPORT-002` | Add optional support-bundle encryption (age/PGP recipient) | SUPPORT-001 | M |

### 6.5 Open questions

- **D1: parser strategy** — committed in §21 but revisit if antlr4rust proves unworkable.
- **D2: workspace vs polyrepo** — committed in R3 but revisit if release cadence diverges sharply between crates.
- Are there additional public PL/SQL corpora worth ingesting (PL/SQL Hub, plsql-utils, Tom Kyte's published examples)?

---

## 7. Layer 1 — Parser Core

### 7.1 Purpose

Take PL/SQL source code as input. Produce a typed, source-position-preserving AST and a token stream. Recover gracefully from syntax errors. Handle every PL/SQL construct that appears in real production code: packages, package bodies, types, type bodies, procedures, functions, triggers (statement + row + compound + INSTEAD OF), views, materialized views, sequences, synonyms, anonymous blocks, dynamic SQL constructs, REF cursors, autonomous transactions, autonomous functions, pragmas, PIPELINED functions, deterministic functions, and DDL statements that bear on dependency analysis (CREATE / ALTER / DROP / GRANT).

### 7.2 Scope of grammar coverage

Required at first close:

- Full PL/SQL Language Reference grammar for Oracle Database 19c (baseline) with 21c / 23ai additions where covered by the ANTLR grammars-v4 grammar
- All DDL statements that create, modify, or drop schema objects relevant to dependency analysis
- DML embedded in PL/SQL (`SELECT`, `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `FOR UPDATE` clauses)
- `EXECUTE IMMEDIATE` (with both static strings and concatenated expressions captured as expression trees)
- `DBMS_SQL` calls (recognized but treated as opaque — see R13)
- Cursor declarations and FETCH/OPEN/CLOSE
- Collections (associative arrays, nested tables, varrays)
- Object types and type bodies
- Inheritance, FINAL/NOT FINAL/INSTANTIABLE
- `REFERENCES` and FK declarations

Out of current GA scope / future-plan items:

- Oracle Pro\*C preprocessing (out)
- SQL\*Plus directives beyond what's needed to delimit statements (only `/` and prompt-text recognition)
- APEX-specific DSL extensions (out)
- 26ai-only constructs not yet in grammars-v4 are routed through `UnsupportedDialectFeature` until grammar support exists upstream

### 7.3 Error recovery requirements

PL/SQL in real-world codebases frequently contains:

- Syntax errors from copy-paste accidents that were never tested
- Vendor-extension constructs in older Oracle versions
- Embedded scripts with mismatched delimiters
- `WHEN OTHERS THEN NULL` blocks that hide further parse-time issues

The parser must:

- Recover at statement boundaries (`;` and `/` delimiters)
- Continue past a malformed PL/SQL block to parse the next block in the same file
- Surface a `Diagnostic` per error with source span
- Never panic on adversarial input

### 7.4 Public API

```rust
pub fn parse_file(input: &str, file_id: FileId) -> ParseResult { ... }
pub fn parse_with_options(input: &str, file_id: FileId, opts: ParseOptions) -> ParseResult { ... }
pub fn parse_with_backend<B: ParseBackend>(input: &str, file_id: FileId, backend: &B, opts: &ParseOptions) -> ParseResult { ... }

pub struct ParseResult {
    pub cst: ConcreteSyntaxTree,
    pub ast: Ast,
    pub tokens: TokenStream,
    pub diagnostics: Vec<Diagnostic>,
    pub recovered: bool,
}

pub struct ConcreteSyntaxTree {
    pub root: CstNodeId,
    pub token_tape: TokenTape,
    pub trivia: TriviaTable,
    pub source_map: SourceMap,
}

pub struct Ast {
    pub root: SourceFile,
    pub source_map: SourceMap,
}

pub trait ParseBackend: Send + Sync {
    fn name(&self) -> &'static str;
    fn parse(&self, input: &str, file_id: FileId, opts: &ParseOptions) -> BackendParseResult;
}
```

**Lossless contract is on the CST/token tape, not the AST.** Every CST node and token carries source-span information. The token tape carries trivia (whitespace, comments) verbatim. The typed AST is **not required** to preserve whitespace, comments, or exact delimiter trivia — it is the semantic shape, not a formatting shape. Round-tripping is performed from the token tape, not from semantic AST pretty-printing. This avoids the AST node bloat that comes from forcing semantic nodes to carry formatting data, and keeps the auto-fix story clean: edits operate on the token tape, not the AST.

### 7.5 Bench + quality targets

Performance:

- Parse the Oracle HR sample schema (~2K lines) in <50ms cold, <5ms warm
- Parse a 10K-line package file in <200ms cold

**Parse-quality targets** on the union of `corpus/public/` + `corpus/synthetic/` (a tolerant parser can always "succeed" by recovering aggressively — single-metric parse-success is a vanity metric):

- Clean parse rate ≥85% (no recovery used)
- Clean-or-recovered parse rate ≥97% (recovery permitted)
- Skipped-token ratio ≤1% across the corpus
- Top-level declaration recognition ≥98% (packages, procedures, functions, triggers, views)
- Unclassified-node ratio ≤2%
- No panic on adversarial corpus

### 7.6 Acceptance criteria

- Parse-quality report meets thresholds in §7.5 (measured by the CI `parse-quality` job)
- Every diagnostic has a non-empty `Span` pointing to the offending source range
- **Round-trip property on token tape**: for any file that lexes successfully, `reconstruct(token_tape(input)) == input` byte-for-byte (proptest)
- Pretty-printing from AST is explicitly non-lossless and tested separately (no byte-for-byte guarantee)
- No panic on any input in `corpus/adversarial/` (fuzz-derived inputs)
- Public API documented at `docs/components/parser.md` (200+ lines) including the AST schema and the CST/token tape contract
- `ParseBackend` conformance test suite passes against the first backend implementation

### 7.7 Implementation strategy

Per R2 + R20 — implement the `ParseBackend` trait first, then implement `AntlrRustBackend` as the first backend candidate. Keep generated ANTLR types **private to the backend crate**. The public parser surface is our lossless CST/token tape plus typed AST — never an ANTLR parse-tree or rule-name.

Author `crates/plsql-parser/build.rs` to generate the Rust ANTLR code at build time inside the backend module. Wrap the generated parser with the high-level API that returns the public types. D2 selects the in-process `antlr4rust` backend as the current production route; the former Java ANTLR subprocess spike was retired on 2026-06-28 and is not an active fallback or workspace crate.

Layered structure within `plsql-parser`:

```
plsql-parser/
├── build.rs            # generates parser from grammar
├── grammar/
│   ├── PlSqlLexer.g4   # vendored from grammars-v4
│   └── PlSqlParser.g4  # vendored from grammars-v4
├── src/
│   ├── lib.rs
│   ├── api.rs          # public ParseResult / Ast types
│   ├── lower.rs        # ANTLR parse tree → our AST
│   ├── recover.rs      # error recovery and statement-boundary detection
│   ├── tokens.rs       # token stream representation
│   └── ast/
│       ├── mod.rs
│       ├── nodes.rs    # all AST node types
│       └── visit.rs    # visitor + walker
└── tests/
    ├── parse_corpus.rs # runs against corpus/
    ├── round_trip.rs   # proptest round-trip
    └── snapshots/      # insta snapshots
```

### 7.8 Bead seeds — Layer 1

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-PARSE-000` | Define `ParseBackend` trait + backend conformance test suite (every backend must pass the same fixture set) | Layer 0 | S |
| `PLSQL-PARSE-000A` | Spike ANTLR Rust codegen against full PL/SQL grammar; record blockers (parse-time, panics, missing features); decision artifact at `docs/decisions/D1-parser-backend-spike.md` | PARSE-000 | M |
| `PLSQL-PARSE-000B` | **Retired 2026-06-28:** former Java ANTLR subprocess spike; removed from the workspace after D2 selected `antlr4rust` | PARSE-000 | M |
| `PLSQL-PARSE-000C` | Parser backend tournament: record the `antlr4rust` decision and no-go/retirement evidence for the Java ANTLR spike; close decision artifact at `docs/decisions/D1-backend-tournament-result.md` | PARSE-000A + PARSE-000B | L |
| `PLSQL-PARSE-000D` | **Retired 2026-06-28:** former neutral wire-protocol sketch for the Java worker; no active implementation path remains | PARSE-000B | M |
| `PLSQL-PARSE-001` | Vendor antlr/grammars-v4 PL/SQL `.g4` files into the antlr4rust backend crate with attribution + license preserved | PARSE-000A | S |
| `PLSQL-PARSE-002` | Author `build.rs` that invokes antlr4rust codegen (inside backend crate, NOT public) | PARSE-001 | M |
| `PLSQL-PARSE-003` | Define public `Ast` + `ConcreteSyntaxTree` + `TokenTape` + `TriviaTable` node hierarchies | Layer 0 | M |
| `PLSQL-PARSE-004` | Implement `lower.rs`: ANTLR parse-tree → public `Ast` for top-level declarations (packages, procedures, functions, triggers, views) | PARSE-002, PARSE-003 | L |
| `PLSQL-PARSE-005` | Implement `lower.rs` for statement bodies (assignments, control flow, EXECUTE IMMEDIATE) | PARSE-004 | L |
| `PLSQL-PARSE-006` | Implement `lower.rs` for expressions (binary ops, function calls, cursor references, attribute access) | PARSE-005 | L |
| `PLSQL-PARSE-007` | Implement `lower.rs` for type declarations (OBJECT types, collections, records) | PARSE-005 | M |
| `PLSQL-PARSE-008` | Implement `lower.rs` for DDL statements (CREATE / ALTER / DROP / GRANT) relevant to dependency analysis | PARSE-004 | L |
| `PLSQL-PARSE-009` | Implement `recover.rs`: error recovery at `;` and `/` boundaries | PARSE-004 | M |
| `PLSQL-PARSE-010` | Implement source-position preservation: every AST node carries a `Span` | PARSE-003 | M |
| `PLSQL-PARSE-011` | Author visitor / walker trait in `src/ast/visit.rs` | PARSE-003 | M |
| `PLSQL-PARSE-012` | Parse-corpus test harness: runs against `corpus/public/` and reports parse-success rate | Layer 0 + PARSE-004 | M |
| `PLSQL-PARSE-013` | Round-trip proptest on **token tape**: `reconstruct(token_tape(s)) == s` byte-for-byte | PARSE-004 | M |
| `PLSQL-PARSE-014` | Insta snapshot tests for 20 representative PL/SQL constructs | PARSE-007 | M |
| `PLSQL-PARSE-015` | Cargo-fuzz harness against the parser; bug-bash for at least 1000 corpus-derived inputs | PARSE-009 | M |
| `PLSQL-PARSE-016` | Benchmark harness in `tools/corpus-bench/` measuring cold/warm parse time across corpus | PARSE-012 | M |
| `PLSQL-PARSE-017` | Document the AST schema at `docs/components/parser.md` (200+ lines) | PARSE-003 + PARSE-004 | M |
| `PLSQL-PARSE-018` | Synthetic test generator in `tools/corpus-grow/` that emits valid PL/SQL from grammar + pattern descriptions | PARSE-004 | L |
| `PLSQL-PARSE-019` | Implement parse-quality metrics + corpus dashboard (clean rate, recovered rate, skipped-token ratio, top-level recognition) | PARSE-012 | M |
| `PLSQL-DIALECT-001` | Define `OracleFeature` registry and `OracleVersion → enabled features` mapping; integrate with `AnalysisProfile::feature_policy` | WS-003 | M |
| `PLSQL-DIALECT-002` | Add parser tests for SQL `BOOLEAN`, `VECTOR`, `SPARSE VECTOR`, vector arithmetic, and `RESETTABLE` where grammar support exists | DIALECT-001 + PARSE-004 | M |
| `PLSQL-DIALECT-003` | Emit `UnsupportedDialectFeature` diagnostics with version-aware remediation hints | DIALECT-001 + PARSE-009 | S |
(Bead rows previously listed here have been relocated to their correct layer tables per the round-5 bead-graph hygiene pass: `PLSQL-CORE-IDS-001` + `PLSQL-SUPPORT-001` + `PLSQL-SUPPORT-002` → Layer 0 §6.4; `PLSQL-SUPPORT-003` → Layer 2 §9.5; `PLSQL-PERF-001`/`PLSQL-PERF-002`/`PLSQL-STORE-DAEMON-001`/`PLSQL-STORE-DAEMON-002` → Layer 2.5 §10A.3.)
| `PLSQL-PLAN-001` | Implement `tools/plan-lint/`: heading-number monotonicity, ToC anchor validity, duplicate bead IDs, missing bead dependencies, stale section references, **component coverage matrix** (every §5 component appears in §6.2.1 + has acceptance criteria + has bead seeds), banned release-wedge language scanner with whitelist for quoted historical changelog blocks | WS-001 | M |
| `PLSQL-PLAN-002` | Add plan-lint to CI; run it before any bead conversion | PLAN-001 + WS-015 | S |
| `PLSQL-PLAN-003` | Normalize all section/subsection numbers and ToC anchors after v0.5+ structural changes. **Target scheme:** every subsection inherits its parent section number (`§11.1`, `§11.2`, ...; `§12.1`, `§12.2`, ...; `§10A.1`, `§10A.2`, ...). No legacy numbers from earlier section positions remain. Current drift to fix: §11 contains `### 10.1`, §12 contains `### 11.2`, §15 contains `### 14.1`, §16 contains `### 15.x`, etc. | PLAN-001 | S |

### 7.9 Open questions

- **D4: dynamic SQL representation** — when `EXECUTE IMMEDIATE` carries a string literal, do we attempt to recursively parse the inner SQL/PL/SQL? Or always represent it as an opaque expression tree with a confidence marker? Recommend recursive parse with explicit "secondary parse" diagnostic shape so it shows up in tools but never blocks the primary parse.
- **D5: cross-file parsing** — does `plsql-parser` accept a single file at a time, or does it accept a project model (multiple files, one schema, optional `CREATE OR REPLACE` ordering)? Recommend single-file-only at Layer 1; cross-file is Layer 2's job.
- Should we expose the underlying ANTLR tree to library users as an escape hatch, or strictly hide it? Recommend strictly hide (R3 — components don't leak implementation details).

---

## 8. Layer 1.5 — Oracle Context (Catalog Snapshot)

### 8.1 Purpose

Source code alone is not enough for credible PL/SQL intelligence. When a live Oracle database is available, **Oracle-native compiler metadata should be used as an optional validation/enrichment source** — Oracle's own compiler is the most authoritative oracle for what PL/SQL means. PL/Scope (compile-time identifier and statement metadata) is the first such source. Real analysis needs Oracle dictionary metadata for:

- `%TYPE` / `%ROWTYPE` resolution (the source declares the dependency; the catalog carries the type)
- Overload signatures (the same procedure name with different parameter lists is a different node)
- Synonyms (public + private; chains that span schemas)
- Grants and privileges (who can execute what, who can read what)
- Indexes (for `PERF003`-class rules)
- Constraints (FK targets, check expressions)
- Triggers (event + timing + body location)
- Generated columns, materialized view refresh dependencies
- Object types and inheritance chains
- Package signatures from already-installed dependencies that are not in the analyzed source

Without this, symbol resolution and bindings generation constantly degrade to guesses. With it, the engine becomes an actual Oracle intelligence platform rather than a source-code parser.

### 8.2 Components

#### 8.2.1 `plsql-catalog` crate

Offline-first Oracle metadata model. Populated from any of:

- A live Oracle connection (using the `oracle` crate or `oracle-rs` per D16)
- An exported JSON snapshot
- `DBMS_METADATA`-derived files committed to the repository
- A synthetic test catalog (corpus-derived)

The parser **never** requires a database connection. Semantic analysis **may optionally** consume a catalog. When a catalog is absent, downstream analysis correctly degrades and records `UnknownReason::MissingCatalogObject` on every affected inference.

Public API:

```rust
pub fn load_snapshot_from_json(path: &Path) -> Result<CatalogSnapshot, CatalogError>;
pub fn load_snapshot_from_connection<C: OracleConnection>(conn: &C, request: &CatalogLoadRequest) -> Result<CatalogSnapshot, CatalogError>;
pub fn export_snapshot_to_json(snapshot: &CatalogSnapshot, path: &Path) -> Result<(), CatalogError>;

pub struct CatalogLoadRequest {
    pub schema_filters: Vec<CatalogSchemaFilter>, // default: [CurrentSchema]
}

pub enum CatalogSchemaFilter {
    CurrentSchema,
    Named(String), // raw Oracle schema name; no hidden SymbolInterner dependency
}

pub struct CatalogSnapshot {
    pub schemas: HashMap<SchemaName, SchemaCatalog>,
    pub profile: AnalysisProfile,
    pub capabilities: CatalogCapabilities,
    pub generated_at: DateTime<Utc>,
    pub source: CatalogSource,
    pub interner: SymbolInterner,             // serialized symbol table so snapshots remain self-describing
}

pub struct SchemaCatalog {
    pub objects: HashMap<ObjectName, CatalogObject>,
    pub synonyms: HashMap<SynonymName, SynonymTarget>,
    pub grants: Vec<Grant>,
    pub indexes: HashMap<IndexName, IndexMetadata>,
    pub constraints: HashMap<ConstraintName, ConstraintMetadata>,
    pub triggers: HashMap<TriggerName, TriggerMetadata>,
    pub dependencies: Vec<CatalogDependency>,    // from ALL_DEPENDENCIES / USER_DEPENDENCIES
    pub plscope: Option<PlScopeSnapshot>,        // when PL/Scope is enabled
}

pub struct ObjectCommon {
    pub owner: SchemaName,
    pub name: ObjectName,
    pub object_type: ObjectType,
    pub status: ObjectStatus,                    // VALID / INVALID / N/A
    pub edition_name: Option<EditionName>,
    pub editionable: Option<bool>,
    pub last_ddl_time: Option<DateTime<Utc>>,
    pub source_hash: Option<Hash>,
    pub ddl: Option<DbmsMetadataDdl>,            // from DBMS_METADATA.GET_DDL
}

pub enum CatalogObject {
    Table(TableMetadata),
    View(ViewMetadata),
    MaterializedView(MViewMetadata),
    Sequence(SequenceMetadata),
    Type(TypeMetadata),
    Package(PackageMetadata),       // signature only — body may be unanalyzed
    Procedure(ProcedureMetadata),
    Function(FunctionMetadata),
    Trigger(TriggerMetadata),
    SchedulerJob(SchedulerJobMetadata),
    EditioningView(EditioningViewMetadata),
}

pub struct CatalogCapabilities {
    pub can_query_dba_views: bool,
    pub can_query_all_views: bool,
    pub can_use_dbms_metadata: bool,
    pub can_read_source: bool,
    pub plscope_enabled: bool,
    pub can_query_scheduler: bool,
    pub can_query_roles_and_grants: bool,
    pub warnings: Vec<CapabilityWarning>,
}
```

The snapshot is intentionally **structural** — it captures shape and signatures, not row data. Because the model uses interned identifier wrappers, the serialized snapshot must also carry its symbol table so exported JSON remains self-describing and reloadable without ambient process state.

#### 8.2.2 `plsql-plscope` module inside `plsql-catalog`

Optional Oracle-native enrichment and validation source. PL/Scope is the PL/SQL compiler's identifier-and-statement metadata, exposed through `ALL_IDENTIFIERS` / `USER_IDENTIFIERS` / `DBA_IDENTIFIERS` and (when enabled) statement metadata. Available since Oracle 11g. Controlled by `PLSCOPE_SETTINGS`.

**PL/Scope is not assumed to be available in customer environments.** It is not collected by default; it requires `PLSCOPE_SETTINGS` to be set before recompilation; collecting all identifiers + statements can produce large data and slow compile time. The plan never makes PL/Scope a hidden prerequisite — it is a compiler-derived comparison source when objects were compiled with suitable settings, and otherwise absent. Its absence does not reduce offline analysis quality.

**Why this matters strategically:** PL/Scope is Oracle's own compiler emitting "where this identifier was used" data. Using it as a differential test source means we can prove our symbol resolver against Oracle's own compiler output. This is the most credible validation strategy available to a third-party PL/SQL analyzer.

Inputs:

- `ALL_IDENTIFIERS` / `USER_IDENTIFIERS` / `DBA_IDENTIFIERS`
- SQL statement metadata where enabled (`PLSCOPE_SETTINGS` includes `STATEMENTS`)
- `PLSCOPE_SETTINGS` for capability detection
- Object compile timestamp + source hash, when available, to detect stale PL/Scope rows
- Warning diagnostics when PL/Scope was requested but not collected due to settings, permissions, or SYSAUX/compiler conditions

Outputs:

- `PlScopeSnapshot`
- `CompilerIdentifier` (name, type, usage kind, owner, line, col)
- `CompilerReference` (resolved declaration link from compiler)
- `CompilerStatementUsage` (SQL statement classified by compiler)
- `PlScopeDiff` — comparing our `plsql-symbols` resolution against PL/Scope's; surfaces missed references, spurious references, kind mismatches

PL/Scope is **never required** for offline analysis. If unavailable, analysis continues and the doctor report records capability status.

### 8.3 Acceptance criteria

- `plsql-catalog` round-trips a snapshot through JSON without loss
- Live-connection extraction against an Oracle XE 23ai container produces the same snapshot as the published JSON fixture (golden test)
- When a snapshot is absent, downstream tools record `UnknownReason::MissingCatalogObject` on every inference that would have benefited
- Catalog extraction includes dependency rows from `ALL_DEPENDENCIES` where permissions allow it (treated as a comparison source, not ground truth)
- `DBMS_METADATA.GET_DDL` extraction populates `ObjectCommon::ddl` when permitted
- PL/Scope extraction populates `SchemaCatalog::plscope` when `PLSCOPE_SETTINGS` allows it
- PL/Scope diff reports one of: `not available`, `available but stale`, `identifiers-only`, or `identifiers-and-statements` as separate states
- PL/Scope is never required for offline correctness gates
- Doctor explains that enabling full PL/Scope can increase compile/storage overhead and should be planned with the customer's DBAs, not blindly forced on production schemas
- Doctor subcommand: `plsql-catalog doctor` reports object counts per schema, last-extracted timestamp, capability matrix (DBA/ALL access, DBMS_METADATA availability, PL/Scope availability, scheduler access, roles/grants access), and suggests the **minimum grants needed** to improve analysis completeness

### 8.4 Bead seeds — Layer 1.5

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-CAT-001` | Define `CatalogSnapshot` + `SchemaCatalog` + `CatalogObject` types | Layer 0 | M |
| `PLSQL-CAT-002` | Implement JSON serializer/deserializer for `CatalogSnapshot` with schema versioning | CAT-001 | S |
| `PLSQL-CAT-003` | Implement `OracleConnection` trait + first sync implementation using `oracle` crate (D16-aware) | CAT-001 | M |
| `PLSQL-CAT-019` | Redesign live catalog loader inputs so schema filters are self-describing (not bare `SchemaName` wrappers) | CAT-003 | S |
| `PLSQL-CAT-004` | Implement live-extraction queries against `ALL_*`/`DBA_*` dictionary views | CAT-003 + CAT-019 | L |
| `PLSQL-CAT-005` | Implement `DBMS_METADATA`-file ingestion path (parses exported DDL files into a catalog) | CAT-001 | M |
| `PLSQL-CAT-006` | Implement synthetic test catalog builder for use in the corpus | CAT-001 | S |
| `PLSQL-CAT-007` | Doctor subcommand: object counts + extraction warnings + missing-permission report | CAT-004 | S |
| `PLSQL-CAT-008` | Integration test: extract snapshot from Oracle XE 23ai container; compare against golden | CAT-004 | M |
| `PLSQL-CAT-009` | Document the catalog crate at `docs/components/catalog.md` (250+ lines) including offline-first philosophy and snapshot schema | CAT-002 | M |
| `PLSQL-CAT-010` | Implement PL/Scope capability detection via `PLSCOPE_SETTINGS` and dictionary views | CAT-004 | M |
| `PLSQL-CAT-011` | Extract `ALL_IDENTIFIERS` / `USER_IDENTIFIERS` into `PlScopeSnapshot` | CAT-010 | M |
(`PLSQL-CAT-012` + `PLSQL-CAT-013` previously lived here but cross the Layer 1.5 → Layer 2 boundary by depending on `SYM-003`. Renamed and relocated to Layer 2 §9.5 as `PLSQL-PLSCOPE-DIFF-001` + `PLSQL-PLSCOPE-DIFF-002`.)
| `PLSQL-CAT-014` | Extract object status, edition, editionable flag, last DDL time, and dependency rows from `ALL_DEPENDENCIES` | CAT-004 | M |
| `PLSQL-CAT-015` | Add `DBMS_METADATA.GET_DDL` (and XML form) extraction and normalization | CAT-004 | M |
| `PLSQL-CAT-016` | Catalog capability report (permissions, missing DBA views, PL/Scope availability, DBMS_METADATA availability) + minimum-grant suggestions | CAT-007 | S |
| `PLSQL-CAT-017` | Implement catalog capability negotiation + grant-suggestion diagnostics in `doctor` | CAT-004 | M |

### 8.5 Open questions

- See D16 (Oracle connection crate selection).

---

## 9. Layer 2 — Semantic IR & Symbol Resolution

### 9.1 Purpose

Take parsed ASTs from one or many files (plus an optional `CatalogSnapshot` from Layer 1.5) and produce a typed semantic intermediate representation (IR) that downstream tools can reason over without re-parsing. Resolve every name (variable, type, procedure, function, package, table, view, column, synonym) to its declaration **with full overload resolution**. Surface unresolved references as explicit diagnostics with a resolution strategy log + structured evidence.

### 9.2 Components

#### 9.2.1 `plsql-ir`

The typed IR. One step removed from the raw AST:

- AST is syntactic; IR is semantic.
- AST has `IdentifierExpr("X")`; IR has `VariableRef { decl: DeclId(42), span: ..., resolved_type: NUMBER }`.
- AST preserves source layout; IR canonicalizes (e.g., qualified names always fully qualified, implicit cursor for-loops desugared).

The IR is the format every downstream tool reads. AST users are rare.

Public types:

```rust
pub struct SemanticModel {
    pub files: Vec<FileModel>,
    pub schemas: HashMap<SchemaName, SchemaModel>,
    pub catalog: Option<CatalogSnapshot>,
    pub privileges: PrivilegeModel,
    pub diagnostics: Vec<Diagnostic>,
}

pub struct FileModel {
    pub file_id: FileId,
    pub top_level: Vec<DeclId>,
    pub statements: Vec<StatementId>,
}

pub struct SchemaModel {
    pub name: SchemaName,
    pub objects: HashMap<ObjectName, ObjectId>,
    pub synonyms: HashMap<SynonymName, ObjectId>,
}
```

#### 9.2.2 `plsql-symbols`

The name resolution engine. Two-pass:

1. **Declaration pass** — walk every parsed AST, register every declaration (package, type, procedure, function, table, view, column, sequence, synonym) into a `DeclTable`.
2. **Reference pass** — walk every reference site; for each, attempt resolution through a chain of strategies; record the strategy that succeeded (or all that failed) in a `Resolution`.

Resolution strategies (in order):

1. Local scope (variables, parameters, cursors)
2. Package-internal (private package items)
3. Same-schema explicit references
4. Synonym indirection (private and public synonyms)
5. Schema-qualified references
6. Catalog-derived (objects present in `CatalogSnapshot` but not in analyzed source)
7. DB-link references (recorded but not resolved — Layer 2 is single-database)

**Overload resolution** is first-class. Procedure/function calls are resolved by arity + named-notation parameters + parameter modes + parameter types + defaults. Where the catalog provides signatures for upstream-installed dependencies, those are considered. When multiple candidates remain, the resolution records all candidates and marks the call as ambiguous.

Output:

- `SymbolTable` with `DeclId → Declaration` mapping
- `ReferenceTable` with `ReferenceSite → Resolution` mapping where `Resolution` is `Resolved(DeclId)`, `ResolvedOverload { primary, alternatives }`, or `Unresolved { reason: UnknownReason, strategies_attempted, evidence }`

#### 9.2.3 Dynamic SQL evidence model

Per R13, for every dynamic SQL site, produce a `DynamicSqlEvidence` record — not just a confidence score, but a structured "here is what we saw and what we concluded":

```rust
pub struct DynamicSqlEvidence {
    pub site: Span,
    pub mechanism: DynamicSqlMechanism,        // ExecuteImmediate, OpenFor, DbmsSqlParse, RefCursorReturn
    pub fragments: Vec<SqlFragment>,           // literal strings, variable refs, function calls
    pub bind_usage: BindUsage,                 // bind vars used vs raw concatenation
    pub sanitizer_usage: Vec<SanitizerCall>,   // DBMS_ASSERT / REGEXP_LIKE / allowlist checks, classified by sanitizer semantics
    pub secondary_parse: Option<SecondaryParseResult>,
    pub candidate_objects: Vec<CandidateObject>,
    pub unresolved_reasons: Vec<UnresolvedReason>,
    pub confidence: Confidence,
    pub injection_risk: InjectionRiskEvidence,
}
```

Resolution behavior:

- Literal string: attempt secondary parse + resolve as normal; record fragments; confidence high if all references resolve.
- Concatenated literal-prefix + variable + literal-suffix: extract fragments; record candidate object name patterns; resolve any deterministic part; confidence medium.
- Fully dynamic (collection iteration, external input): record as opaque with confidence 0; fragments + bind-usage + sanitizer-usage still captured.

**Sanitizer usage is evidence, not proof of safety.** The engine classifies sanitizer calls by what they validate:

- `DBMS_ASSERT.SIMPLE_SQL_NAME` — validates a simple unqualified SQL identifier
- `DBMS_ASSERT.QUALIFIED_SQL_NAME` — validates a qualified SQL identifier (e.g. `schema.object`)
- `DBMS_ASSERT.SCHEMA_NAME` — validates a schema name
- `DBMS_ASSERT.ENQUOTE_LITERAL` — produces a quoted literal value
- `DBMS_ASSERT.SQL_OBJECT_NAME` — validates an existing object name
- `REGEXP_LIKE` against allowlist patterns
- Custom allowlist comparisons (enum-bounded value sets)
- Numeric coercion / date parsing
- Unknown — observed but not classified

A sanitizer that validates an **identifier** does not sanitize an arbitrary SQL **predicate** or **literal value**. SAST findings must check the sanitizer family matches the sink context; "DBMS_ASSERT observed" alone is not safety proof.

This produces evidence customers can act on. Customer-facing diagnostics show: the exact span, the expression fragments, whether bind variables were used, whether `DBMS_ASSERT` (or equivalent) validation was observed, candidate object names if inferred, and the reason static resolution stopped.

#### 9.2.4 `plsql-privileges` crate

Models authorization-relevant semantics — distinct from raw catalog data because it combines source-code annotations (`AUTHID`, `ACCESSIBLE BY`) with catalog-derived grants and roles:

- Definer-rights vs invoker-rights units
- Grants to users, roles, `PUBLIC`
- Synonym visibility under different invoker identities
- Runtime ambiguity from roles
- Security-sensitive cross-schema writes
- `ACCESSIBLE BY` access lists (white-listed callers)

Output feeds SAST evidence, lineage confidence, and CI/CD risk reports. Distinct enough from symbol resolution to be its own crate; sharing types with `plsql-symbols` via `plsql-core`.

#### 9.2.5 `plsql-ir::fact` — normalized fact store

**Why this layer exists:** without an explicit intermediate fact model, each product surface (SAST, lineage, docs, bindgen) would walk the raw IR independently and re-interpret semantics. Over time they would drift — SAST resolving a name one way, lineage another, docs another. A normalized fact store gives every consumer the same answers to the same questions.

The current implementation lives in `plsql-ir` (`fact.rs`, `fact_emit.rs`,
`sql_fact_emit.rs`). There is **no** separate `plsql-facts` crate in this
workspace. The fact store is **not** a Datalog/Prolog system on day one. It is a
set of relational fact families with stable schemas and content-addressed IDs:

```rust
pub enum FactKind {
    Declaration,
    Reference,
    DependencyEdge,
    DynamicSqlEvidence,
    DbLinkReference,
    Opacity,
    ResolutionReport,
    Privilege,
    ConstantValue,
    ValueSet,
    StringShape,
    Taint,
    Sanitizer,
    // plus SAST/domain fact families such as ExceptionHandler,
    // CrossSchemaWrite, SensitivePublicSynonym, and others.
}

pub struct FactStore { /* facts indexed by kind */ }
```

**All product surfaces consume `FactStore` first** and only drop to raw IR for component-specific details:

- `plsql-sast` rules query facts
- `plsql-lineage` builds impact graphs from facts
- `plsql-doc` renders documentation from facts
- `plsql-bindgen` emits bindings from facts
- `plsql-cicd` predicts invalidation from facts

#### 9.2.6 `plsql-ir` flow state and emitted-fact projection

**Why this layer exists:** the v0.4 SAST and dynamic-SQL story jumped from syntax to findings without a dataflow engine. Real SQL injection analysis needs to answer: where did the dynamic string come from? Did user input enter it? Was DBMS_ASSERT used? Was the value bound or concatenated? Was the table name selected from a bounded set?

The working solver is a `plsql-ir` flow-state model (`FlowEnv`, `FlowQuery`,
`RoutineFlowSummary`, `FlowUnknownFact`, and related intra/inter-procedural
modules). There is **no** separate `plsql-flow` crate. The solver models
conservative value flow across PL/SQL variables, parameters, assignments,
branches, string operations, cursor loops, and procedure calls.

Phase G (`oracle-plsql-converge-0lnu.14`) was the tracked build of the intended
end-state: keep the solver, but materialize its evidence as normalized
`FactStore` rows. That projection produces stable `ConstantValue`, `ValueSet`,
`StringShape`, `Taint`, `Sanitizer`, and `Opacity`/unknown facts via
`plsql-ir::fact_emit`, with golden snapshots and fact-ID-stability coverage.

The important distinction is architectural: flow **state** is internal solver
machinery; emitted flow **facts** are the cross-surface contract.

Representative emitted fact families:

```rust
FactKind::Taint               // source -> sink path for security analysis
FactKind::ConstantValue       // literal or compile-time constant value
FactKind::ValueSet            // bounded set of possible values
FactKind::StringShape         // concatenation template with literal + symbolic segments
FactKind::Sanitizer           // observed validation (DBMS_ASSERT, REGEXP_LIKE, etc.)
FactKind::Opacity             // loop/alias/call boundary where flow remains conservative
```

Consumers:

- `plsql-sast` — SQL injection (SEC001/SEC002) and hardcoded-secret rules consume taint paths + string shapes
- `plsql-symbols` — dynamic-SQL candidate extraction uses string shapes
- `plsql-lineage` — dynamic-edge confidence pulls from value-set facts
- `plsql-bindgen` — `Defaulted<T>` Omit/Null/Value diagnostics use constant value facts

Without this layer, SAST findings on dynamic SQL would be either too noisy (false positives on any `EXECUTE IMMEDIATE`) or too weak (missing real injections inside loop-built strings). With it, SAST becomes evidence-based instead of regex-with-good-intentions.

#### 9.2.7 `plsql-ir` embedded-SQL semantic model

PL/SQL intelligence is not only PL/SQL. Most customer-facing value (especially column-level lineage) comes from understanding **embedded SQL**. Treating SQL analysis as scattered special cases in `plsql-ir` would have created a pile of brittle edge cases. A separate semantic model for SQL statements is the right abstraction.

That semantic model now lives as `plsql-ir` modules and emits normalized facts
through `sql_fact_emit.rs`; there is **no** separate `plsql-sqlsem` crate.

Responsibilities:

- Table alias resolution
- `SELECT` projection modeling
- CTE / subquery scopes
- DML target/source distinction
- `MERGE` source/target roles
- `RETURNING INTO` handling
- Column read/write classification
- Static SQL inside dynamic-SQL secondary parses

Emits `SqlStatementModel` records consumed by `plsql-depgraph`, `plsql-lineage`, `plsql-sast`, and `plsql-bindgen`:

```rust
pub struct SqlStatementModel {
    pub statement_id: StatementId,
    pub kind: SqlStatementKind,                  // SELECT, INSERT, UPDATE, DELETE, MERGE, ...
    pub tables: Vec<TableUse>,
    pub columns: Vec<ColumnUse>,
    pub projections: Vec<ProjectionItem>,
    pub aliases: AliasScope,
    pub confidence: Confidence,
    pub evidence: Evidence,
}

pub struct SqlSemanticModel {
    pub statements: HashMap<StatementId, SqlStatementModel>,
    pub diagnostics: Vec<Diagnostic>,
}
```

This is the difference between table-level lineage (which v0.2 could produce) and credible column-level lineage. Without it, column lineage would have remained a brittle afterthought.

#### 9.2.6 DDL statement registration

Tables, views, materialized views, sequences, types, synonyms, indexes, constraints, triggers — every CREATE statement registers its target object in the schema model. ALTER updates. DROP removes (but is recorded for historical analysis).

### 9.3 Public API

```rust
pub fn analyze_files(
    files: Vec<(FileId, Ast)>,
    config: SemanticConfig,
) -> SemanticModel { ... }

pub struct SemanticConfig {
    pub profile: AnalysisProfile,                // canonical environment (replaces v0.2's scattered fields)
    pub additional_schemas: Vec<SchemaName>,
    pub catalog: Option<CatalogSnapshot>,
    pub treat_db_links_as_opaque: bool,
    pub dynamic_sql_strategy: DynamicSqlStrategy,
}
```

### 9.4 Acceptance criteria

- 90%+ of references in `corpus/public/` resolve cleanly when a matching catalog is supplied; declarations not present anywhere correctly recorded as `Unresolved { reason: MissingCatalogObject | DbLinkRemoteObject | ... }`
- Every `EXECUTE IMMEDIATE` produces a `DynamicSqlEvidence` record (never silently dropped)
- Every reference in the output `ReferenceTable` has either a `DeclId`, an `Overload` resolution, or a non-empty `strategies_attempted` list with reasons + evidence
- Overload resolution passes a fixture suite of 50+ named/positional overload calls against the synthetic corpus
- `plsql-privileges` correctly classifies definer-rights and invoker-rights units across package specs, package bodies, standalone routines, and nested calls in synthetic fixtures
- `plsql-privileges` resolves direct grants, role grants, `PUBLIC` grants, private synonyms, public synonyms, and `ACCESSIBLE BY` fixtures into `PrivilegeFact` records
- Role-mediated authorization produces `UnknownReason::RuntimeGrantOrRole` where runtime role state would change the result
- Invoker-rights cross-schema read/write paths emit evidence records consumable by SAST `SEC004` and lineage confidence scoring
- Privilege doctor reports grant coverage, unresolved authorization edges, role-dependent edges, `PUBLIC` exposure surface, and cross-schema write surface
- `plsql-ir` embedded-SQL modules resolve table aliases, CTE scopes, subqueries, DML target/source roles, `MERGE` roles, and `RETURNING INTO` fixtures with expected table/column-use facts
- `plsql-ir` embedded-SQL fact emission never emits exact column lineage for `SELECT *`, `NATURAL JOIN`, unsupported view expansion, or dynamic projections — it emits precision-tiered unknowns instead
- `plsql-ir` flow-state fixture suite includes at least 10 cases each for: constants, bounded value sets, string concatenation templates, tainted parameter flow, sanitizer classification, loop boundaries, unresolved-call boundaries, and inter-procedural parameter/return flow
- `plsql-ir` emitted-fact projection emits expected `ConstantValue`, `ValueSet`, `StringShape`, `Taint`, `Sanitizer`, and opacity/unknown fact records for those fixtures with golden JSON snapshots
- `plsql-ir` flow analysis is conservative at loops, unresolved calls, aliasing boundaries, and dynamic dispatch — no rule may treat missing flow as proof of safety
- `plsql-ir::FactStore` round-trips every `FactKind` through the in-memory store with stable fact IDs across two identical runs; any persisted projection remains a `plsql-store` responsibility
- Fact IDs remain stable across whitespace/comment-only source changes where the underlying semantic identity is unchanged
- Every product surface has one integration test proving it can answer its common inventory query from `FactStore` without raw AST traversal: SAST rule input, doc object inventory, bindgen package inventory, lineage edge input, and CI/CD change classification input
- Doctor subcommand (`plsql-ir doctor`) reports symbol-resolution health on the corpus

### 9.5 Bead seeds — Layer 2

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-IR-001` | Define `SemanticModel`, `FileModel`, `SchemaModel` types in `plsql-ir` | Layer 1 | M |
| `PLSQL-IR-002` | Define `DeclId`, `Declaration` enum (Variable, Param, Cursor, Procedure, Function, Package, Type, Table, View, Column, Sequence, Synonym, Index, Trigger) | IR-001 | M |
| `PLSQL-IR-003` | Implement AST→IR lowering for top-level declarations | IR-002 | L |
| `PLSQL-IR-004` | Implement AST→IR lowering for statement bodies (control flow, assignments, SQL DML) | IR-003 | L |
| `PLSQL-IR-005` | Implement AST→IR lowering for expressions and references | IR-004 | M |
| `PLSQL-IR-006` | Add canonicalization (fully-qualified names, desugaring of implicit cursor for-loops) | IR-005 | M |
| `PLSQL-SYM-001` | Implement `DeclTable` + declaration registration pass | IR-002 | M |
| `PLSQL-SYM-002` | Implement reference resolution strategies 1-3 (local, package-internal, same-schema) | SYM-001 + IR-005 | M |
| `PLSQL-SYM-003` | Implement reference resolution strategies 4-5 (synonyms, schema-qualified) | SYM-002 | M |
| `PLSQL-SYM-004` | Implement DB-link reference recording (no resolution; opaque external) | SYM-003 | S |
| `PLSQL-SYM-005` | Implement dynamic SQL `DynamicSqlEvidence` model: fragments, bind usage, DBMS_ASSERT detection, candidate-object inference | SYM-002 | M |
| `PLSQL-SYM-006` | Implement `Resolution` reporting with strategy trace + structured `Evidence` records | SYM-002 | S |
| `PLSQL-SYM-007` | Doctor subcommand reporting resolution health on corpus | SYM-006 | S |
| `PLSQL-SYM-008` | End-to-end test: parse + resolve a 10-file synthetic package; verify cross-package references resolved | SYM-003 | M |
| `PLSQL-SYM-009` | Implement overload identity + call resolution with named/positional notation, parameter modes, defaults, and catalog-derived signatures | SYM-003 + CAT-004 | L |
| `PLSQL-SYM-010` | Feed catalog `%TYPE`/`%ROWTYPE`/synonyms/overloads/indexed-column facts into symbol resolution | SYM-009 + CAT-004 | L |
| `PLSQL-PRIV-001` | Define privilege model: users, roles, grants, `PUBLIC`, definer/invoker rights, `ACCESSIBLE BY` | CAT-001 | M |
| `PLSQL-PRIV-002` | Feed privilege ambiguity into symbol-resolution confidence and SAST evidence | PRIV-001 + SYM-003 | M |
| `PLSQL-PRIV-003` | Doctor subcommand reporting privilege graph + cross-schema-write surface on corpus | PRIV-002 | S |
| `PLSQL-SQLSEM-001` | Define `SqlStatementModel`, `TableUse`, `ColumnUse`, `ProjectionItem`, `AliasScope`, `SqlSemanticModel` types | IR-005 + CAT-001 | M |
| `PLSQL-SQLSEM-002` | Implement table/alias resolution for `SELECT`/`INSERT`/`UPDATE`/`DELETE`/`MERGE` | SQLSEM-001 + SYM-003 | L |
| `PLSQL-SQLSEM-003` | Implement projection + column read/write extraction with evidence | SQLSEM-002 | L |
| `PLSQL-SQLSEM-004` | Emit SQL table/column-use facts with exact/expression/unknown precision markers | SQLSEM-003 + FACT-001 | M |
| `PLSQL-FLOW-001` | Define value-flow, taint, constant, value-set, and string-shape models | IR-005 + SYM-005 | M |
| `PLSQL-FLOW-002` | Implement intra-procedural assignment and expression flow | FLOW-001 | L |
| `PLSQL-FLOW-003` | Implement bounded inter-procedural parameter/return flow (with conservative `FlowUnknownFact` at boundaries) | FLOW-002 + SYM-009 | L |
| `PLSQL-FLOW-004` | Feed dynamic-SQL `StringShapeFact` into `DynamicSqlEvidence` | FLOW-002 + SYM-005 | M |
| `PLSQL-FLOW-005` | Expose taint-path and string-shape query API for SAST and dynamic-SQL consumers (Layer 2 must not depend on Layer 3) | FLOW-003 | M |
| `PLSQL-FACT-001` | Define normalized fact schema (`FactKind` enum, per-family types) with stable fact IDs | SQLSEM-001 + PRIV-001 + SYM-006 | M |
| `PLSQL-FACT-002` | Emit declaration/reference/call facts from semantic model | FACT-001 | M |
| `PLSQL-FACT-003` | Emit SQL table/column-use facts from the `plsql-ir` embedded-SQL model | FACT-001 + SQLSEM-003 | M |
| `PLSQL-FACT-004` | Emit privilege, dynamic-SQL, and unknown facts with evidence | FACT-001 + PRIV-002 + SYM-005 | M |
| `PLSQL-FACT-005` | Persist and query facts through `plsql-store` (in-memory + SQLite backends) | FACT-001 + WS-006 | M |
| `PLSQL-SUPPORT-003` | Add literal classifier (credential-like, SQL-like, URL-like, free-text, numeric, date/time, unknown) for dynamic-SQL evidence + diagnostics | SUPPORT-001 + FLOW-001 | M |
| `PLSQL-PLSCOPE-DIFF-001` | Implement PL/Scope diff: compare our symbol references against PL/Scope references | CAT-011 + SYM-003 | L |
| `PLSQL-PLSCOPE-DIFF-002` | PL/Scope-backed golden tests against Oracle XE where available | PLSCOPE-DIFF-001 | M |

### 9.6 Open questions

- **D6: cross-database analysis** — when a customer hands us a multi-schema export, do we analyze each schema independently, or do we attempt cross-schema resolution? Recommend cross-schema-as-default with a flag to disable. This is the more useful behavior; isolation can be retrofitted.

---

## 10. Layer 2 — Dependency Graph Builder

### 10.1 Purpose

Given a `SemanticModel`, emit a directed dependency graph where **nodes are stable semantic identities** (schema objects, package members, overloads, local routines, columns, constraints, triggers, generated artifacts) and edges are typed relationships (calls, reads, writes, references). Edges carry both **provenance** (source file, span, kind, resolution strategy) and **evidence** (the structured "why we believe this edge exists" record).

### 10.2 Edge kinds

| Edge | Meaning |
|------|---------|
| `Calls` | PL/SQL procedure/function A calls procedure/function B |
| `Reads` | A reads from table/view/column B |
| `Writes` | A writes to (INSERT/UPDATE/DELETE/MERGE) table B |
| `ReadsColumn` | A reads from specific column (deterministic mapping) |
| `WritesColumn` | A writes to specific column (deterministic mapping) |
| `DerivesColumn` | Target column is derived from one or more source columns through an expression (precision tier: `ExpressionColumnLineage`) |
| `ReadsUnknownColumnOfTable` | Statement reads a table, but exact columns are not statically recoverable (precision tier: `TableScopedColumnUnknown`) |
| `WritesUnknownColumnOfTable` | Statement writes a table, but exact target columns are not statically recoverable |
| `References` | A references a sequence, synonym, type, etc. |
| `TriggersOn` | Trigger A fires on event of table B |
| `DependsOnType` | A's signature or body uses a type defined by B |
| `Constrains` | FK constraint A references B |
| `OpaqueDynamic` | A may interact with B according to dynamic SQL analysis (confidence < 1.0) |
| `DbLink` | A interacts with remote object B over DB link |

### 10.3 Confidence + Evidence model

Every edge carries **both** a `Confidence` value and an `Evidence` record. Customer-facing tools must show evidence summaries for low-confidence and security-relevant edges (not just the score).

Confidence value `∈ [0.0, 1.0]`:

- 1.0 — fully static reference, name resolved deterministically
- 0.9 — same as above but through a synonym chain (synonym targets can change)
- 0.7 — partial dynamic SQL with deterministic prefix (e.g., `'INSERT INTO ' || schema_name || '.LOG_TBL'` where `schema_name` is bounded)
- 0.5 — dynamic SQL with bounded enumeration possible
- 0.3 — dynamic SQL with shape known but target uncertain
- 0.0 — fully opaque (e.g., DBMS_SQL fed from external input)

Customer-facing tools surface confidence as bands (high/medium/low/opaque) by default; raw scores available via `--robot-json`.

### 10.4 Output format

```rust
pub struct DepGraph {
    pub nodes: HashMap<NodeId, Node>,
    pub edges: Vec<Edge>,
    pub provenance: HashMap<EdgeId, Provenance>,
    pub evidence: HashMap<EdgeId, Evidence>,
}

pub struct Node {
    pub id: NodeId,
    pub logical_id: LogicalObjectId,             // deterministic from schema/name/member/signature
    pub revision_id: ObjectRevisionId,           // hash of semantic declaration/body shape
    pub persistent_id: Option<PersistentObjectId>, // DB/catalog-derived if available
    pub display_name: QualifiedName,
    pub identity_kind: NodeIdentityKind,         // SpecDeclaration, BodyImplementation, StandaloneProcedure, LocalNestedRoutine, ...
    pub overload_signature: Option<OverloadSignature>,
}

pub struct Edge {
    pub id: EdgeId,
    pub from: NodeId,
    pub to: NodeId,
    pub kind: EdgeKind,
    pub confidence: Confidence,
}

pub struct Provenance {
    pub file: FileId,
    pub span: Span,
    pub resolution_strategy: ResolutionStrategy,
    pub notes: Vec<String>,
}
```

Serializable to: JSON, GraphML (consumed by Gephi, yEd, Cytoscape), GraphViz dot, JSON Lines for streaming.

### 10.5 Acceptance criteria

- For every CALL site in the corpus, an outgoing `Calls` edge exists from caller to callee (or an `OpaqueDynamic` edge with `DynamicSqlEvidence` attached)
- For every SQL DML statement, the appropriate Reads/Writes edges exist
- For live catalog fixtures, depgraph extraction is compared against Oracle `ALL_DEPENDENCIES` rows; differences classified as `our extra edge`, `Oracle-only edge`, `kind mismatch`, `expected gap`, `dynamic-sql-only`, `wrapped-source`, `missing-privilege`, or `catalog-stale`
- `SELECT *`, `NATURAL JOIN`, `USING`, view expansion, and dynamic projections **never** produce fake exact column edges — they produce `ReadsUnknownColumnOfTable` / `DerivesColumn` with appropriate precision-tier markers
- Column lineage reports must separate `ExactColumnLineage`, `ExpressionColumnLineage`, `TableScopedColumnUnknown`, and `DynamicColumnUnknown` edges (no false precision)
- The graph is explainable by `plsql-depgraph explain <edge-id|node-id|path-id>` (see DEP-015)
- Every node has three layers of identity:
  - `LogicalObjectId` — deterministic from schema + name + member + signature; stable across source-position/comment/body-format changes
  - `ObjectRevisionId` — content hash of semantic declaration + body shape; changes when semantic shape changes
  - `PersistentObjectId` — Oracle dictionary `OBJECT_ID` where catalog metadata allows
- **Renames are not silently merged.** An offline source analyzer cannot know whether a renamed object is "the same thing renamed" or "one deleted, another created" without external help. Renames are represented as delete+create unless an explicit rename mapping or catalog-derived persistent ID links them. `classify-rename` (§14.2) emits candidate mappings with confidence.
- Overloaded procedures produce distinct nodes per signature; SpecDeclaration and BodyImplementation are distinct identity kinds
- No edge lacks a `Provenance` entry; no low-confidence edge lacks an `Evidence` entry
- GraphML output validates against the GraphML schema
- The graph is queryable by `plsql-depgraph query` CLI with at least these operations: `neighbors`, `path`, `reverse-neighbors`, `cycle-detect`

### 10.6 Bead seeds — Layer 2 (continued)

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-DEP-001` | Define `DepGraph`, `Node` (with `LogicalObjectId` + `ObjectRevisionId` + optional `PersistentObjectId` + `NodeIdentityKind` + `OverloadSignature`), `Edge`, `EdgeKind`, `Provenance`, `Evidence` types | Layer 2 (IR) | M |
| `PLSQL-DEP-002` | Implement edge extraction for `Calls` (procedure/function invocations) | DEP-001 + SYM-002 | M |
| `PLSQL-DEP-003` | Implement edge extraction for `Reads` / `Writes` (DML statements at table level) | DEP-001 + SYM-002 | M |
| `PLSQL-DEP-004` | Implement edge extraction for `ReadsColumn` / `WritesColumn` / `DerivesColumn` / `ReadsUnknownColumnOfTable` / `WritesUnknownColumnOfTable` from SQL semantic facts | DEP-003 + SQLSEM-004 + FACT-003 | L |
| `PLSQL-DEP-005` | Implement edge extraction for `TriggersOn` (trigger event → table mapping) | DEP-001 | S |
| `PLSQL-DEP-006` | Implement edge extraction for `Constrains` (FK constraints) | DEP-001 | S |
| `PLSQL-DEP-007` | Implement confidence scoring for dynamic SQL edges | DEP-002 + SYM-005 | M |
| `PLSQL-DEP-008` | Implement DB-link edge recording | DEP-001 + SYM-004 | S |
| `PLSQL-DEP-009` | Implement GraphML serializer **in `plsql-depgraph`** using `plsql-output` envelope helpers (component-owned per R5) | DEP-001 + Layer 0 | S |
| `PLSQL-DEP-010` | Implement GraphViz `.dot` serializer **in `plsql-depgraph`** using render helpers | DEP-001 + Layer 0 | S |
| `PLSQL-DEP-011` | Implement `plsql-depgraph query` CLI with `neighbors`, `path`, `reverse-neighbors`, `cycle-detect` operations | DEP-001 | M |
| `PLSQL-DEP-012` | End-to-end test: build dep graph for synthetic 30-package corpus; verify expected edges + cycle detection | DEP-007 | M |
| `PLSQL-DEP-013` | Doctor subcommand: report graph statistics + low-confidence-edge inventory on corpus | DEP-011 | S |
| `PLSQL-DEP-014` | Implement catalog-dependency cross-check report: compare depgraph edges against `ALL_DEPENDENCIES`; classify mismatches as (our-extra, oracle-only, kind-mismatch, expected-gap) | DEP-001 + CAT-014 | M |
| `PLSQL-DEP-015` | Implement `plsql-depgraph explain <edge-id\|node-id\|path-id>`: print provenance + evidence (source span, SQL/PLSQL statement, resolution strategy, catalog facts, confidence, dynamic-SQL evidence) | DEP-001 | M |

---

## 10A. Layer 2.5 — Analysis Orchestration

### 10A.1 Purpose

`plsql-engine` is the canonical pipeline boundary. It constructs exactly one reproducible `AnalysisRun` from project input, parser backend, catalog source, analysis profile, cache policy, redaction policy, and output schema version. Product surfaces consume this artifact rather than recomposing lower-layer crates. Without this canonical artifact, SAST, lineage, docs, and bindgen would each compose the lower layers slightly differently and drift over time — by quarter four, the same name would resolve three different ways.

### 10A.2 Acceptance criteria

- `plsql analyze` emits an `AnalysisRun` artifact that includes: project, parse results, catalog summary, semantic model summary, SQL semantic summary, flow summary, fact-store reference, depgraph, completeness report, diagnostics, and artifact manifest.
- Re-running `plsql analyze` on unchanged input produces stable artifact IDs, except for explicitly marked volatile metadata (timestamps in the manifest header).
- Changing any field in `AnalysisProfile` invalidates every affected cached fragment in `plsql-store`.
- Downstream CLIs (`plsql-sast`, `plsql-doc`, `plsql-bindgen`, `plsql-lineage`, `plsql-cicd`, `plsql-accretion`, `usr-loop`) can consume an existing `AnalysisRun` without reparsing source.
- The engine refuses to mix incompatible `plsql-output` schema versions between cached fragments and consumers.
- `plsql-engine doctor` reports parser backend, catalog capability, cache hit ratio, fact-store status, graph status, and completeness block.

### 10A.3 Bead seeds — Engine

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-ENG-001` | Define `AnalysisRequest`, `AnalysisRun`, `AnalysisArtifactManifest`, and schema-version compatibility checks | PARSE-003 + CAT-001 + IR-001 + FACT-001 + DEP-001 | M |
| `PLSQL-ENG-002` | Wire canonical pipeline: project → parse → catalog → IR → symbols → privileges → sqlsem → flow → facts → depgraph; emit `CompletenessReport`. Blocks until every Layer 2 component bead is closed | ENG-001 + FACT-005 + FLOW-004 + DEP-007 | L |
| `PLSQL-ENG-003` | Wire cache reuse through `plsql-store` using content hashes + profile hashes (profile changes invalidate cached fragments) | ENG-002 + WS-006 | M |
| `PLSQL-ENG-004` | Add `plsql analyze` umbrella command emitting reusable `AnalysisRun` artifact consumed by all downstream CLIs | ENG-002 | M |
| `PLSQL-ENG-005` | Implement `plsql-engine doctor` reporting backend, catalog capability, cache hit ratio, fact-store status, graph status, and completeness block | ENG-004 | S |
| `PLSQL-PERF-001` | Implement AST eviction + compact persisted analysis mode | ENG-003 + FACT-005 | L |
| `PLSQL-PERF-002` | Add `plsql doctor memory` + `--memory-profile` output | PERF-001 | M |
| `PLSQL-STORE-DAEMON-001` | Define local-daemon protocol for querying cached `AnalysisRun` + fact-store artifacts | ENG-004 + FACT-005 | M |
| `PLSQL-STORE-DAEMON-002` | Implement optional `plsqld` local daemon (no network telemetry, explicit cache directory) | STORE-DAEMON-001 | L |

---

## 11. Layer 3 — Documentation Generator

### 11.1 Purpose

Generate readable documentation from PL/SQL source. Replaces the abandoned PLDoc category. Produces Markdown + static HTML site (Docusaurus-compatible) with: package summaries, procedure/function signatures, parameter tables, call graphs (rendered inline), table-usage graphs, comment extraction (including `/** ... */` doc comments), cross-references between objects.

### 11.2 Output structure

A generated `docs/` directory with:

```
docs/
├── index.md                     # entry point with schema-level summary
├── schemas/
│   └── <schema>/
│       ├── index.md
│       ├── packages/
│       │   └── <package>.md     # one file per package
│       ├── tables/
│       │   └── <table>.md
│       ├── views/
│       │   └── <view>.md
│       └── triggers/
│           └── <trigger>.md
├── _assets/
│   ├── callgraph-<package>.svg
│   └── usage-<table>.svg
└── _meta/
    ├── manifest.json            # generation provenance, version, source-rev
    └── stats.json               # objects-documented count, coverage percentage
```

### 11.3 Doc comment conventions

The generator recognizes Oracle-conventional comment styles plus a new `/** */` JavaDoc-style convention:

```sql
/**
 * @description Compute least-cost route for a destination + customer.
 * @param p_dest_e164 Destination phone number in E.164 format
 * @param p_customer_id Customer ID
 * @returns Route object containing chosen carrier and rate
 * @raises -20001 if no rate card applies
 * @see x$rate.get_card
 */
FUNCTION find_route(p_dest_e164 VARCHAR2, p_customer_id NUMBER)
    RETURN route_t;
```

Tags supported: `@description`, `@param`, `@returns`, `@raises`, `@see`, `@since`, `@deprecated`, `@author`, `@example`.

If no doc comments exist, generator falls back to:

- Signature from declaration
- Inferred description from comment lines immediately preceding the declaration (legacy convention)
- Empty body section with a "not documented" notice

### 11.4 Call graph rendering

For each procedure/function, render the local call graph (this procedure + its direct callers/callees) as inline SVG, generated from the dep-graph in Layer 2. Limit depth to 2 by default; configurable.

### 11.5 Acceptance criteria

- Given a 10-file synthetic test package, generate docs that include every public declaration
- Every generated page has a stable URL (anchor by fully-qualified object name)
- Every reference in a doc page is a working hyperlink (no broken cross-refs)
- Call graphs and table-usage graphs render correctly in major browsers
- `plsql-doc --serve` opens a local HTTP server for preview
- Doctor subcommand: report doc coverage (% of objects with doc comments) on corpus

### 11.6 Bead seeds — Doc

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-DOC-001` | Define `DocSet`, `ObjectDoc`, `DocComment` types in `plsql-doc` | Layers 1+2 | S |
| `PLSQL-DOC-002` | Implement doc-comment lexer for `/** */` and legacy preceding-line conventions | DOC-001 | M |
| `PLSQL-DOC-003` | Implement tag parser: `@description`, `@param`, etc. | DOC-002 | M |
| `PLSQL-DOC-004` | Implement object-page renderer for packages (Markdown + HTML) | DOC-003 + Layer 0 | M |
| `PLSQL-DOC-005` | Implement object-page renderer for tables, views, triggers, sequences | DOC-004 | M |
| `PLSQL-DOC-006` | Implement inline SVG call-graph rendering from dep-graph | DOC-004 + Layer 2 | M |
| `PLSQL-DOC-007` | Implement table-usage graph rendering | DOC-006 | S |
| `PLSQL-DOC-008` | Implement schema-index page with object inventory + search affordances | DOC-005 | M |
| `PLSQL-DOC-009` | Implement Docusaurus-compatible MDX export for embedding into existing sites | DOC-005 | S |
| `PLSQL-DOC-010` | Implement `plsql-doc --serve` local HTTP preview server | DOC-005 | S |
| `PLSQL-DOC-011` | Doctor subcommand: doc-coverage report | DOC-008 | S |
| `PLSQL-DOC-012` | End-to-end test: generate docs for synthetic 30-package corpus; verify no broken links | DOC-010 | M |

---

## 12. Layer 3 — Static Analysis (SAST)

### 12.1 Purpose

Rule-based scanner for security, quality, and performance issues in PL/SQL. GA ships a **precision-tiered rule pack** — high-confidence defaults enabled out of the box, medium-confidence rules clearly marked + suppressible, house-style and experimental rules opt-in only. Rule pack is extensible internally; customer-defined rules SDK out of scope at first close (D11).

**Why precision tiers matter:** SAST tools die from false positives. The original "20 baseline rules" list included several rules that are too noisy or technically weak (missing `WHEN OTHERS` is not generally a defect; `IS NULL` on indexed column is too simplistic without catalog evidence; missing instrumentation is house-style not a defect). The pack below restructures these into tiers and tightens the rule definitions.

### 12.2 Baseline rule pack (20 rules)

| Rule ID | Category | Description |
|---------|----------|-------------|
| `SEC001` | Security | `EXECUTE IMMEDIATE` with concatenated input → SQL injection risk |
| `SEC002` | Security | `DBMS_SQL.PARSE` fed by non-literal or unvalidated string evidence (plain `DBMS_SQL` usage is review-only, not a default finding) |
| `SEC003` | Security | Hardcoded credential literals (`PASSWORD = '...'`, `IDENTIFIED BY '...'`) |
| `SEC004` | Security | Invoker-rights unit reaches privileged object through ambiguous runtime authorization (uses `plsql-privileges`) |
| `SEC005` | Security | Public synonym creation for sensitive objects (configurable list) |
| `SEC006` | Security | `GRANT ... TO PUBLIC` |
| `SEC007` | Security (opt-in) | REF cursor returned from invoker-facing API without configured authorization-predicate evidence; **disabled by default** — requires shop-specific configuration of what "authorization predicate" means |
| `QUAL001` | Quality | Exception handler swallows error without re-raise/logging (`WHEN OTHERS THEN NULL` and structural variants) |
| `QUAL002` | Quality | Exception handler logs only via configurable weak logger and then continues without re-raise |
| `QUAL003` | Quality | Unbounded `FETCH` without `LIMIT` clause |
| `QUAL004` | Quality | `COMMIT` or `ROLLBACK` inside non-transactional procedure body (unexpected side effect) |
| `QUAL005` | Quality | Use of deprecated features (e.g., `SQL_TRACE`, `UTL_FILE` without alternatives) |
| `QUAL006` | Quality | Trigger that writes to its own table (`Mutating Table` risk) |
| `QUAL007` | Quality | Hidden DML inside a function (functions should be side-effect-free) |
| `QUAL008` | Quality | Non-deterministic function declared `DETERMINISTIC` |
| `STYLE001` | House Style (opt-in) | Missing instrumentation according to configured house policy; **disabled by default** |
| `PERF001` | Performance | Row-by-row DML inside loop where source cardinality is statically high or configured high-risk (requires evidence) |
| `PERF002` | Performance | Implicit cursor in `FOR` loop with `INSERT/UPDATE` inside (use `FORALL`) |
| `PERF003` | Performance | Predicate likely prevents intended index usage — only when catalog evidence confirms index type and column nullability |
| `DEP001` | Dependency | Cross-schema write detected (configurable; flag for review) |

### 12.3 Rule architecture

Each rule is a trait implementor with explicit precision tiering:

```rust
pub trait Rule: Send + Sync {
    fn id(&self) -> &'static str;
    fn precision(&self) -> PrecisionTier;
    fn evidence_requirements(&self) -> &'static [EvidenceKind];
    fn required_facts(&self) -> &'static [FactKind];
    fn minimum_completeness(&self) -> CompletenessRequirement;
    fn description(&self) -> &'static str;
    fn category(&self) -> Category;
    fn default_severity(&self) -> Severity;
    fn scan(&self, model: &SemanticModel, facts: &FactStore, ctx: &mut ScanContext);
    fn default_enabled(&self) -> bool {
        matches!(
            self.precision(),
            PrecisionTier::HighConfidenceDefault | PrecisionTier::MediumConfidenceDefault,
        )
    }
}

pub struct CompletenessRequirement {
    pub requires_catalog: bool,
    pub requires_privileges: bool,
    pub requires_flow: bool,
    pub requires_sqlsem: bool,
    pub allow_unknowns: bool,
}

pub enum PrecisionTier {
    HighConfidenceDefault,    // enabled out of the box
    MediumConfidenceDefault,  // enabled, but clearly marked + easily suppressible
    HouseStyleOptIn,          // disabled by default
    ExperimentalOptIn,        // disabled by default; may have unstable behavior
}
```

If a rule's `evidence_requirements()` or `minimum_completeness()` are not met (e.g., the catalog is missing and the rule needs index metadata; or flow analysis is unavailable and the rule needs taint paths), the rule emits `RuleSkippedDiagnostic` — **not** a weak finding. Skipped diagnostics explain exactly which evidence/facts/completeness conditions were missing, so customers can decide whether to enable the missing capability (catalog snapshot, PL/Scope, flow analysis) or accept the skip.

This makes SAST explainable: a finding is justified by specific facts and evidence, not by "the rule said so."

A `ScanContext` accumulates findings. Each finding includes: rule ID, severity, span, message, structured `Evidence` from the rule's analysis, optional fix suggestion (text only at first close — auto-fix is deferred).

### 12.4 Output

- Default: human-readable terminal output (miette-rendered)
- `--format json` — `--robot-json` shape
- `--format sarif` — SARIF 2.1.0 for SIEM/code-review-tool ingestion
- `--format junit` — JUnit XML for CI failure reporting
- `--baseline <file>` — compare against a baseline, only report new findings (for incremental adoption)
- **Stable finding fingerprints** survive harmless line shifts and formatting changes:
  ```rust
  pub struct Finding {
      pub rule_id: RuleId,
      pub severity: Severity,
      pub span: Span,
      pub message: String,
      pub evidence: Evidence,
      pub fingerprint: FindingFingerprint,
      pub suppression_state: SuppressionState,
  }

  pub struct FindingFingerprint {
      pub primary: Hash,   // rule + semantic object id + normalized evidence (survives reformatting)
      pub location: Hash,  // file path + normalized span context (survives small line shifts)
  }
  ```
- **Suppressions**: config-based plus inline comments (`-- plsql-scan:ignore RULE` / `-- plsql-scan:ignore-next-line RULE`)

### 12.5 Acceptance criteria

- All rules implemented with at least 5 positive test cases (`corpus/synthetic/sast-pos/<rule-id>/`) and 5 negative test cases (`corpus/synthetic/sast-neg/<rule-id>/`)
- **High-confidence default rules** must meet ≤5% false positives on the negative corpus
- **Medium-confidence default rules** are clearly marked, easily suppressible, and target ≤15% false positives
- **House-style and experimental rules** are disabled by default; quality bar is "useful for shops that opt in"
- Every default-enabled security rule declares `required_facts()` and `minimum_completeness()`. Rules that cannot meet evidence requirements emit `RuleSkippedDiagnostic`, never weak findings
- SEC001/SEC002 findings include a taint path or `StringShapeFact` reference when available (from `plsql-ir` emitted flow facts)
- False-negative rate on the positive corpus ≤5% for high-confidence rules
- SARIF output validates against the official SARIF 2.1.0 schema (emitted from `plsql-scan`'s own renderer per R5)
- Doctor subcommand: per-rule firing count + per-rule tier on a corpus, useful for tuning

### 12.6 Bead seeds — SAST

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-SAST-001` | Define `Rule` trait, `ScanContext`, `Finding`, `RuleSkippedDiagnostic` types | FACT-001 + FLOW-005 | S |
| `PLSQL-SAST-002` | Implement scan harness: load `AnalysisRun` / `FactStore` → run all enabled rules (honoring `required_facts` + `minimum_completeness`) → emit findings and skipped diagnostics | SAST-001 + ENG-004 + FACT-005 | M |
| `PLSQL-SAST-003` | Implement SEC001 (`EXECUTE IMMEDIATE` injection) using flow taint/string-shape evidence + tests | SAST-002 + FLOW-005 | S |
| `PLSQL-SAST-004` | Implement SEC002 (`DBMS_SQL.PARSE`) using flow taint/string-shape evidence + tests | SAST-002 + FLOW-005 | S |
| `PLSQL-SAST-005` | Implement SEC003 (hardcoded credentials) + tests | SAST-002 | S |
| `PLSQL-SAST-006` | Implement SEC004 (`AUTHID CURRENT_USER`) + tests | SAST-002 | S |
| `PLSQL-SAST-007` | Implement SEC005 (public synonym on sensitive objects) + tests | SAST-002 | S |
| `PLSQL-SAST-008` | Implement SEC006 (`GRANT TO PUBLIC`) + tests | SAST-002 | S |
| `PLSQL-SAST-009` | Implement SEC007 (REF cursor return) + tests | SAST-002 | M |
| `PLSQL-SAST-010` | Implement QUAL001 (`WHEN OTHERS THEN NULL`) + tests | SAST-002 | S |
| `PLSQL-SAST-011` | Implement QUAL002 (weak logging + continue without re-raise) + tests | SAST-002 | S |
| `PLSQL-SAST-012` | Implement QUAL003 (unbounded FETCH) + tests | SAST-002 | S |
| `PLSQL-SAST-013` | Implement QUAL004 (unexpected COMMIT/ROLLBACK) + tests | SAST-002 | S |
| `PLSQL-SAST-014` | Implement QUAL005 (deprecated features) + tests | SAST-002 | M |
| `PLSQL-SAST-015` | Implement QUAL006 (mutating table risk) + tests | SAST-002 | M |
| `PLSQL-SAST-016` | Implement QUAL007 (hidden DML in function) + tests | SAST-002 | S |
| `PLSQL-SAST-017` | Implement QUAL008 (`DETERMINISTIC` misuse) + tests | SAST-002 | M |
| `PLSQL-SAST-018` | Implement STYLE001 (missing instrumentation per house policy, opt-in) + tests | SAST-002 | S |
| `PLSQL-SAST-019` | Implement PERF001 (cursor for-loop bulk-collect) + tests | SAST-002 | S |
| `PLSQL-SAST-020` | Implement PERF002 (cursor for-loop FORALL) + tests | SAST-002 | S |
| `PLSQL-SAST-021` | Implement PERF003 (IS NULL on indexed column) + tests | SAST-002 + Layer 2 (column metadata) | M |
| `PLSQL-SAST-022` | Implement DEP001 (cross-schema write) + tests | SAST-002 + Layer 2 | S |
| `PLSQL-SAST-023` | Implement SARIF 2.1.0 output formatter | SAST-002 + Layer 0 | M |
| `PLSQL-SAST-024` | Implement JUnit XML output formatter | SAST-002 + Layer 0 | S |
| `PLSQL-SAST-025` | Implement `--baseline` mode for incremental adoption | SAST-002 | M |
| `PLSQL-SAST-026` | Doctor subcommand: per-rule firing histogram | SAST-002 | S |
| `PLSQL-SAST-027` | False-positive measurement harness against synthetic negative corpus | SAST-022 | M |
| `PLSQL-SAST-028` | Implement stable `FindingFingerprint` (primary + location hashes) for SARIF + baseline matching | SAST-002 | M |
| `PLSQL-SAST-029` | Implement suppressions: config-based + inline `-- plsql-scan:ignore RULE` / `ignore-next-line` comments | SAST-028 | M |

### 12.7 Open questions

- **D11: rule pack expansion path** — after the 20 baseline rules ship, do we author rules in-house, or stand up a rule SDK so customers and the community author rules? Recommend: in-house for the first 50 rules (avoid maintenance burden of supporting a public SDK before the product is proven); revisit at 100-rule mark.

---

## 13. Layer 3 — Bindings Generator

### 12.1 Purpose

Generate type-safe Rust bindings from PL/SQL package specs and table/view declarations. Eliminates hand-coded Oracle access from any Rust service that calls PL/SQL business logic. GA scope: Rust target only. Go and TypeScript deferred (D7).

### 12.2 Output shape

Given an input like:

```sql
CREATE OR REPLACE PACKAGE x$lcr AS
    TYPE route_t IS RECORD (
        carrier_id  NUMBER,
        rate        NUMBER(18, 8),
        valid_from  TIMESTAMP
    );
    FUNCTION find_route(p_dest_e164 VARCHAR2,
                        p_customer_id NUMBER,
                        p_call_time TIMESTAMP DEFAULT SYSTIMESTAMP)
        RETURN route_t;
END;
```

Generate:

```rust
//! Generated from x$lcr — do not edit by hand.
//! Source: schema=PRODUCTION file=x_lcr.PKG line=1
//! Generator version: plsql-bindgen 0.1.0
//! Generation timestamp: 2026-05-11T14:30:00Z

use rust_decimal::Decimal;
use chrono::{DateTime, Utc};
use oracle::Connection;

pub mod x_lcr {
    use super::*;

    #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
    pub struct Route {
        pub carrier_id: i64,
        pub rate: Decimal,
        pub valid_from: DateTime<Utc>,
    }

    pub fn find_route<E: OracleExecutor>(
        exec: &mut E,
        p_dest_e164: &str,
        p_customer_id: i64,
        p_call_time: Defaulted<DateTime<Utc>>,
    ) -> Result<Route, BindingError> {
        // ... generated body using exec
    }
}
```

**Sync-first by design.** Generated bindings target a small `OracleExecutor` trait. The first production backend is the synchronous `oracle` crate (ODPI-C). Generated async wrappers are **out of scope for this release** — the generator must not emit fake-async wrappers over a blocking driver. Customer code may wrap the sync API manually using an explicit blocking thread-pool (`tokio::task::spawn_blocking`) if needed, but that integration lives in customer code, not in generated output. The mature `oracle` crate is sync; pretending it's async in the generated API is dishonest and creates subtle production hazards.

**Defaulted parameter semantics.** Oracle parameters with `DEFAULT` expressions require a three-state distinction that `Option<T>` cannot express:

```rust
pub enum Defaulted<T> {
    Omit,        // do not bind the parameter; let the server apply the DEFAULT expression
    Null,        // bind explicit NULL
    Value(T),    // bind explicit value
}
```

Conflating "omit" with "null" produces wrong results when the server's DEFAULT differs from `NULL`. `Defaulted<T>` is mandatory wherever the source declares a `DEFAULT`.

### 12.3 Type mapping

| Oracle type | Rust type |
|-------------|-----------|
| `NUMBER(n,0)` (`n ≤ 18`) | `i64` |
| `NUMBER(n,0)` (`n > 18`) | `rust_decimal::Decimal` |
| `NUMBER(n,m)` | `rust_decimal::Decimal` |
| `BINARY_FLOAT` | `f32` |
| `BINARY_DOUBLE` | `f64` |
| `VARCHAR2(n)` | `String` |
| `CHAR(n)` | `String` |
| `CLOB` | `String` |
| `BLOB` | `Vec<u8>` |
| `DATE` | `OracleDateTime` (configurable backend) — date+time, no fractional seconds, no timezone; do not silently widen |
| `TIMESTAMP` | `OracleTimestamp` (configurable backend) — fractional precision preserved up to driver capability |
| `TIMESTAMP WITH TIME ZONE` | `OracleTimestampTz` preserving offset/region where the driver exposes it; optional opt-in UTC normalization |
| `TIMESTAMP WITH LOCAL TIME ZONE` | `OracleTimestampLtz` documented as session-local normalized value; **never blindly mapped to `chrono::Local`** in generated server code |
| `INTERVAL DAY TO SECOND` | `chrono::Duration` |
| `INTERVAL YEAR TO MONTH` | custom `IntervalYM` type |
| `RAW(n)` | `Vec<u8>` |
| SQL `BOOLEAN` (23ai+) | `bool` where driver supports it |
| PL/SQL `BOOLEAN` parameter | `bool` only when invocation backend supports PL/SQL boolean binding; otherwise emit unsupported diagnostic (PL/SQL BOOLEAN predates SQL BOOLEAN and is not always client-bindable) |
| `XMLTYPE` | `String` (or `roxmltree::Document` opt-in) |
| `JSON` (21c+) | `serde_json::Value` |
| `REF CURSOR` | `Unsupported(RefCursor)` `BindingDiagnostic` by default; generated row type only when `.plsql-bindgen.toml` provides an explicit manual row-shape override |
| Custom OBJECT type | Generated struct |
| Nested table | `Vec<T>` |
| Associative array (PL/SQL only) | `HashMap<K, V>` (passing requires `oracle` crate support; otherwise unsupported with diagnostic) |
| `VARRAY` | `Vec<T>` |

Nullable handling distinguishes three states clearly:

- **Nullable value (no DEFAULT)**: `Option<T>`. `None` means bind explicit NULL.
- **Defaulted parameter (with DEFAULT)**: `Defaulted<T>`. `Omit` lets server apply default; `Null` binds NULL explicitly; `Value(T)` binds an explicit value.
- **Nullable AND defaulted**: `Defaulted<Option<T>>` — yes, both layers matter and customers will hit this.

### 12.4 Hard parts

- **Overloaded procedures**: Rust does not support function overloading by parameter type. Generate `find_route_by_dest_and_customer(...)`, `find_route_by_dest_and_customer_at_time(...)`, etc. Suffixes derived from parameter names.
- **REF cursors**: first GA emits an `Unsupported(RefCursor)` `BindingDiagnostic` unless an explicit manual row-shape override is provided in `.plsql-bindgen.toml`. Automatic projection inference belongs to a future bindings-extension plan (resolves the v0.4 contradiction with §2.3 which listed REF cursor projection inference as a non-goal).
- **`%TYPE` / `%ROWTYPE`**: requires Layer 2 symbol resolution to map back to the original table/column type. If unresolvable, emit `String` + warning.
- **Package-level state (variables, types declared in spec)**: types are emitted; variables are not directly bindable, generate getter/setter procs if found.
- **Pipelined functions**: first GA emits an `Unsupported(Pipelined)` `BindingDiagnostic` with a manual-wrapper template. Automatic `Stream` emission belongs to a future bindings-extension plan.
- **OUT and IN OUT parameters**: function returns tuple `(T_return, T_out1, T_out2, ...)` or generated `<Fn>Output` struct if more than 3 OUT/IN OUT params.
- **Date/time precision**: 23ai+ supports `TIMESTAMP(9)`; verify Rust types (chrono is microsecond-resolution; for nanoseconds use `time::PrimitiveDateTime` or document loss).
- **Sync vs async execution**: generated bindings target a small `OracleExecutor` trait. The first production backend is sync `oracle`. Async wrappers are optional and must not fake async over blocking calls — if used, they must explicitly spawn through `tokio::task::spawn_blocking` and be clearly labeled.
- **Date/time backend**: generated bindings support a configurable time backend (`time` crate, `chrono`, or custom wrapper types). Default preserves Oracle semantics rather than eagerly normalizing — losing offset/zone information silently is a footgun.
- **PL/SQL `BOOLEAN` vs SQL `BOOLEAN`**: treated separately; the generator tests actual driver capability before emitting a `bool` binding for PL/SQL parameters.

### 12.5 Acceptance criteria

- Given the synthetic private-estate-shaped test package (authored from grammar + descriptions, NOT from private estate source), generate bindings that compile cleanly under `cargo build`
- Generated bindings round-trip values through a real Oracle Database (test against `oracle-rs` or `oracle` crate in CI using Oracle XE 23ai container)
- For every unsupported construct, emit a `BindingDiagnostic` with the source span and a suggested manual workaround
- REF cursor and pipelined-function declarations produce deterministic `BindingDiagnostic` entries — **never** partial generated wrappers
- Manual override files (`.plsql-bindgen.toml`) can declare explicit row shapes for selected REF cursor APIs as a stop-gap before the future extension lands
- The generator's output is deterministic — the same input always produces the same output (no timestamps in the generated code body, only in header comments)

### 12.6 Bead seeds — Bindgen

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-BG-000` | Define `BindingPlan` IR (input: SemanticModel; output: per-package binding spec) | Layers 1+2 | M |
| `PLSQL-BG-001` | Define `OracleExecutor` trait + sync-first execution model + optional async wrapper (explicit blocking-pool semantics) | BG-000 + D16 | M |
| `PLSQL-BG-002` | Implement Oracle→Rust type mapping with all entries from §12.3 | BG-001 | M |
| `PLSQL-BG-003` | Implement struct emission for OBJECT types and records | BG-002 | M |
| `PLSQL-BG-004` | Implement function/procedure wrapper emission | BG-003 | L |
| `PLSQL-BG-005` | Implement IN/OUT/IN OUT parameter handling with tuple/struct return | BG-004 | M |
| `PLSQL-BG-006` | Implement `%TYPE` / `%ROWTYPE` resolution via Layer 2 symbol table | BG-002 | M |
| `PLSQL-BG-007` | Implement overload disambiguation strategy (parameter-name-based suffixes) | BG-004 | M |
| `PLSQL-BG-008` | Emit `Unsupported(RefCursor)` `BindingDiagnostic` plus optional manual row-shape override hook (deterministic, never partial wrappers) | BG-004 | M |
| `PLSQL-BG-009` | Emit `Unsupported(Pipelined)` `BindingDiagnostic` plus manual-wrapper template | BG-004 | S |
**Future bindings-extension placeholders** (NOT bead seeds for this plan; not converted by `beads-workflow`):

- Automatic REF CURSOR row-type inference where projection is static
- Pipelined-function `Stream` emission

These belong to a future bindings-extension plan with its own refinement cycle.
| `PLSQL-BG-010` | Implement `Defaulted<T>` semantics: `Omit` vs `Null` vs `Value(T)` distinction across IN/OUT/IN OUT | BG-005 | S |
| `PLSQL-BG-011` | Implement `BindingDiagnostic` for unsupported constructs | BG-001 | S |
| `PLSQL-BG-012` | Implement `plsql-bindgen` CLI with `--package <name>`, `--output <dir>`, `--target rust` | BG-004 | M |
| `PLSQL-BG-013` | Doctor subcommand: bindings-coverage report | BG-012 | S |
| `PLSQL-BG-014` | CI: spin up Oracle XE 23ai container, deploy a synthetic test package, generate bindings, run a round-trip integration test | BG-012 | L |
| `PLSQL-BG-015` | Document the binding generator at `docs/components/bindings.md` (250+ lines) including type-mapping table, hard-parts caveats, manual-override patterns | BG-012 | M |
| `PLSQL-BG-016` | Implement configurable date/time backend + `OracleDateTime` / `OracleTimestamp` / `OracleTimestampTz` / `OracleTimestampLtz` wrapper types | BG-002 | M |
| `PLSQL-BG-017` | Add PL/SQL `BOOLEAN` vs SQL `BOOLEAN` driver-capability tests; emit unsupported diagnostic when client cannot bind PL/SQL `BOOLEAN` | BG-014 | M |

### 12.7 Open questions

- **D7: target language expansion** — Go via cgo or native? TypeScript via Node `oracledb` or via REST gateway? Recommend deferring until Rust has 5+ paying customers; Go is the more credible second target.
- **D10: licensing of generated code** — generated Rust code is the customer's. The generator binary is dual-licensed (R16). Generated code carries no license header beyond an attribution comment.

---

## 13A. External MCP Integration (`oraclemcp`)

### 13A.1 Purpose

This repository no longer ships an MCP server. Its current responsibility is the offline PL/SQL intelligence engine and stable CLI/library surfaces. MCP transport, live Oracle sessions, guarded writes, connection discovery, registry distribution, and production operations belong in the separate `oraclemcp` repository.

`oraclemcp` may expose PL/SQL intelligence by depending on the engine crates from this workspace and translating MCP tool calls into `AnalysisRun` and report-artifact operations. That integration is an external consumer contract, not a new Layer 3 or Layer 5 crate in this repo.

| Surface | Owner | Contract |
|---------|-------|----------|
| Offline parse / analyze / report generation | `plsql-intelligence` | Stable Rust APIs plus CLI/robot-JSON artifacts from `plsql-engine`, `plsql-lineage`, `plsql-sast`, `plsql-doc`, `plsql-bindgen`, `plsql-cicd`, and `plsql-accretion` |
| MCP protocol, stdio/TCP transport, tool registry, client metadata, distribution | `oraclemcp` | External MCP host consumes engine crates or CLI artifacts and exposes whichever tools it chooses |
| Live Oracle connections, query execution, guarded writes, audit sinks, driver selection | `oraclemcp` | External live I/O boundary. This repo must not add live sockets or driver/runtime dependencies for MCP serving |
| Shared compatibility evidence | both repos | `plsql-intelligence` publishes library contracts and golden artifacts; `oraclemcp` owns MCP/live end-to-end tests against those contracts |

Current implementation rule: new beads in this repo must not add an MCP server crate, MCP binary, live-DB feature graph, stdio server, or Oracle connection runtime for serving agents. File cross-repo follow-up issues against `oraclemcp` when MCP/live behavior is needed.

### 13A.2 External integration contract

For `oraclemcp` to consume this engine cleanly, this repo guarantees:

- `AnalysisRun` remains the canonical analysis artifact for project-wide semantics.
- Robot-JSON envelopes stay versioned through `plsql-output`; MCP hosts should forward these structured payloads instead of scraping human text.
- Every uncertainty stays explicit as `UnknownReason` with provenance, including parser recovery, missing catalog metadata, dynamic SQL opacity, wrapped code, and DB-link ambiguity.
- Trust Block data remains available on report-producing surfaces so an MCP host can expose confidence and blind spots without inventing a second model.
- Offline engine commands do not require Oracle credentials, Java, daemon state, or network access in the normal path.
- Live database validation, if offered to agents, is an `oraclemcp` responsibility and must be tested there against this repo's published artifacts.

### 13A.3 Retired historical `plsql-mcp` notes

The remaining v0.9-v0.12 text in this section is retained only as historical provenance. It is not active implementation guidance, and its bead seeds must not be converted into this repo's work queue.

The MCP server uses the standard Model Context Protocol: stdio transport by default (matches every MCP client in 2026), optional TCP for remote agents. Tool descriptions follow the `mcp-server-design` skill's agent-friendly patterns — clear names, structured inputs, error envelopes with remediation hints, idempotent semantics.

**Static-analysis tools** (`plsql-mcp`, Apache-2.0 OR MIT):

| Tool | Input | Output | Engine dependency |
|------|-------|--------|-------------------|
| `analyze_project` | project root path + optional `AnalysisProfile` | `AnalysisRun` summary + cache key | `plsql-engine` |
| `parse_file` | file path or inline source | parse diagnostics + token tape summary + AST node count | `plsql-parser` |
| `get_symbol` | qualified name | declaration site, signature, overloads, definer/invoker rights, grants | `plsql-symbols` + `plsql-privileges` |
| `find_callers` | qualified name | direct callers + transitive callers up to N hops, with evidence | `plsql-depgraph` |
| `find_callees` | qualified name | direct callees + transitive callees up to N hops, with evidence | `plsql-depgraph` |
| `get_dependencies` | object id | full dependency neighborhood (in + out edges) | `plsql-depgraph` |
| `dynamic_sql_evidence` | file path + line range OR object id | `DynamicSqlEvidence` records for all dynamic SQL sites in scope (expression fragments, bind-vs-concat classification, candidate names, confidence per candidate) | `plsql-ir` flow state + `FactStore` |
| `completeness_report` | scope (file / package / project) | Trust Block (§1.5) at the requested scope | `plsql-engine` |
| `compile_check` | inline PL/SQL source | parse + symbol-resolution diagnostics; no execution, no DB connection | `plsql-parser` + `plsql-symbols` |
| `doc_lookup` | object id | rendered markdown documentation for the object (signatures, doc comments, examples) | `plsql-doc` |
| `inspect_profile` | none | current `AnalysisProfile` (Oracle version, current schema, current edition, `PLSQL_CCFLAGS`, enabled roles, DB-link policy) | `plsql-engine` |

**Live-DB connectivity tools** (`plsql-mcp`, Apache-2.0 OR MIT; available when the `live-db` Cargo feature is enabled; normal runtime connections use `oraclemcp-db` -> `oracledb` and do not require Oracle Instant Client):

| Tool | Safety class | Input | Output / behavior |
|------|--------------|-------|-------------------|
| **Connection management** | | | |
| `list_connections` | Read-only | none | Saved Oracle connections discovered on host: TNS aliases, EZConnect entries, Wallet bundles, `~/.dbtools` profiles. Inherits whatever the underlying Oracle driver supports |
| `connect` | Read-only | connection name OR DSN string | Connection handle ID + connection metadata (Oracle version, edition, current schema, current user, NLS, role list, active safety profile, read/write posture, `permanently_read_only` flag) |
| `disconnect` | Read-only | connection handle | Success acknowledgement |
| `current_database` | Read-only | none | Active connection details + active safety profile + posture |
| `switch_database` | Read-only | connection name | New active connection metadata; previous handle released |
| **Query** | | | |
| `query` | Read-only | SQL SELECT + bind values | Structured rows + column metadata; LOB content scrubbed for MCP / prompt-injection markers per K18; rejects non-SELECT statements |
| **Live schema browsing** | | | |
| `list_objects` | Read-only | type filter + name pattern + schema filter | Structured object list (name, type, status, last_ddl_time, owner) from `ALL_OBJECTS` / `DBA_OBJECTS` (whichever the user can see) |
| `describe_table` | Read-only | qualified table name | Columns + types + nullability + constraints + indexes + comments + partition info |
| `describe_view` | Read-only | qualified view name | View DDL + columns + base-object dependencies |
| `describe_trigger` | Read-only | qualified trigger name | Trigger DDL + table + event + timing + status |
| `describe_index` | Read-only | qualified index name | Index DDL + columns + type + status |
| **Live source access** | | | |
| `get_object_source` | Read-only | qualified object name | Source from `DBA_SOURCE` / `ALL_SOURCE` |
| `get_clob` | Read-only | CLOB identifier | CLOB content with K18 prompt-injection sanitization |
| `get_errors` | Read-only | qualified object name | Structured `USER_ERRORS` / `ALL_ERRORS` rows |
| **Compile** | | | |
| `compile_with_warnings` | Requires write enablement | qualified object name | `ALTER ... COMPILE` with `PLSQL_WARNINGS = ENABLE:ALL`; returns structured diagnostics + warning categories (severe / informational / performance) |
| **Patch & deploy** | | | |
| `preview_sql` | Read-only (dry-run) | proposed DDL OR patch operation (find/replace/insert against named object) | DDL that *would* be generated + a single-use approval token. Never executes |
| `read_patch_preview` | Read-only | approval token | Full DDL preview for inspection before approval |
| `patch_package` | Per-operation approval | package name + find + replace + mode (`dry-run` \| `apply`) | Targeted REPLACE-based package-body or spec edit. In `dry-run` mode returns approval token; in `apply` mode requires a fresh token from `preview_sql` |
| `patch_view` | Per-operation approval | view name + find + replace + mode | Same flow as `patch_package` |
| `create_or_replace` | Per-operation approval | full DDL statement (CREATE OR REPLACE) | Full DDL deployment; requires prior `preview_sql` token |
| `deploy_ddl` | Per-operation approval | DDL statement + wait_seconds | Lock-free deployment via `DBMS_SCHEDULER` (pattern: a one-shot `PLSQL_BLOCK` scheduler job; avoids library-cache locks on busy objects) |
| **Write posture** | | | |
| `enable_writes` | Operator-explicit | confirmation token from operator (NOT from agent) | Session-level writes enabled; safety profile transitions to `session_write_enabled`. Refused on `permanently_read_only` connections |
| `disable_writes` | Read-only | none | Revoke session-level writes |
| `execute_approved` | Per-operation approval | approval token + statement | Execute a previously-previewed DDL/DML. Token is single-use, time-limited (60s default), tied to the exact previewed SQL; re-running `preview_sql` invalidates prior tokens |

**Safety classes:**

- **Read-only** — always callable; no DB mutation possible by construction
- **Requires write enablement** — refuses until `enable_writes` was called for the session
- **Per-operation approval** — must be paired with `preview_sql` first, then `execute_approved` (or the tool's own `apply` mode) with the preview's approval token
- **Operator-explicit** — requires a confirmation token supplied by the human operator (not derivable by the agent)

**Hard guards:**

- `permanently_read_only` config flag per connection (in `~/.plsql-mcp/connections.toml`) — refuses `enable_writes` and every write tool regardless of session state. Set on production database connections. Mirrors the safety pattern in a proven production Oracle MCP server
- Interactive schema-name confirmation for cross-schema write operations (operator must type the schema name to proceed)
- Every emitted SQL statement carries `/* plsql-mcp $tool $session-id $agent-model */` as a comment for audit visibility
- Session tagged via `DBMS_APPLICATION_INFO.SET_MODULE('plsql-mcp', $tool_name)` so DBAs see consistent vendor markers in `V$SESSION.MODULE` / `V$SESSION.ACTION` (matches the convention Oracle SQLcl MCP uses)

**Change-impact tools** (`plsql-mcp`, module `change_tools`, Apache-2.0 OR MIT):

| Tool | Input | Output | Engine dependency |
|------|-------|--------|-------------------|
| `what_breaks` | proposed changeset (diff or DDL) | direct + transitive impact, recompile order, Oracle-dictionary cross-check, uncertain edges with `UnknownReason` | `plsql-lineage` |
| `classify_change` | diff or DDL changeset | `SemanticChangeSet` — semantic vs cosmetic, signature impact, package-state implications | `plsql-lineage` |
| `compare_oracle_deps` | optional schema filter | engine-vs-`ALL_DEPENDENCIES` cross-check report | `plsql-lineage` |
| `sarif_scan` | scope | SARIF document with high-confidence rules first, RuleSkippedDiagnostic for missing-evidence rules | `plsql-scan` |
| `release_gate` | changeset + policy file | gate verdict + per-threshold detail | `plsql-cicd` |
| `recompile_plan` | changeset | topologically-sorted DDL + COMPILE statements | `plsql-cicd` |
| `orphan_candidates` | optional scope filter | tier-partitioned orphan list (§13.8) with AUDIT statements | `plsql-lineage` |
| `explain_lifecycle` | changeset | Oracle lifecycle effects (invalidation, reauthorization, edition impact, package-state discard, etc.) | `plsql-cicd` |

**No license gating.** `plsql-mcp` advertises its full tool surface in `tools/list` — static-analysis, live-DB connectivity, and change-impact tools alike. There is no license key, no entitlement check, and no fallback mode; every tool is available to every user on a plain `cargo install plsql-mcp`.

### 13A.3 Architecture

**One binary, one tool surface.** `plsql-mcp` is a single crate and a single binary. Static-analysis, live-DB connectivity, and change-impact tools all link against the same `Apache-2.0 OR MIT` workspace crates. A `cargo install plsql-mcp` user has the whole surface, including `what_breaks`, with nothing to unlock.

**Transport.** stdio is the default — matches MCP client expectations and works in every IDE today. Optional TCP transport behind a flag (`--listen 127.0.0.1:NNNN`) for remote agent sessions, with the same caveat as everywhere else in the plan: no outbound calls, no telemetry, no inbound traffic from outside the customer's network.

**Engine integration.** The MCP server is a thin protocol shim around `plsql-engine` — it does NOT duplicate analysis logic. Each tool call:

1. Resolves the AnalysisRun (cache hit via content-addressed `plsql-store`, or fresh analysis if needed)
2. Queries the engine's stable library API
3. Wraps the result in MCP's response envelope plus the Trust Block (§1.5) as a structured `meta` field
4. Returns

This means daemon mode (D17) is the natural backend for the MCP server. The MCP server keeps a persistent engine instance hot in memory, serving multiple tool calls without restart cost. R7 already specifies Tokio for daemon mode, which fits MCP's async-friendly transport naturally.

**Error handling.** Every tool returns a structured error with: `UnknownReason` if relevant, a remediation hint, and a confidence band. Errors are NOT exceptions — they are first-class results with provenance, matching the Evidence UX brand promise (§1.5). An agent that gets *"I couldn't resolve `foo.bar` because no catalog snapshot is loaded; run `analyze_project` with `--catalog <snapshot.json>` to fix"* is in a position to actually take the next step.

**Trust Block in every response.** Every MCP tool response includes a `meta.trust_block` field carrying the same Trust Block payload as CLI / HTML / SARIF reports. Agents (or the human developer reading the agent's output) can see at a glance: parsed 94% clean, 7 opaque dynamic-SQL sites, catalog snapshot age, exact column lineage 72%. The brand promise that "every customer-visible report" includes the Trust Block (§1.5) applies to MCP responses identically.

**Live-DB connectivity (foundation, Apache-2.0).** v0.10 absorbed the basic live-Oracle surface that the workspace's existing `oracle-mcp/server.py` had been providing. `plsql-mcp` ships a `live-db` Cargo feature (default-on for the binary, optional for the library — so static-analysis-only embedding remains possible). When `live-db` is enabled, the live-DB tool surface from §13A.2 becomes available through the published `oraclemcp-db` thin backend. When `live-db` is disabled, the binary still works (static-analysis tools always function) and the doctor subcommand reports the disabled feature explicitly.

**Connection management.** Runtime sessions are opened through `oraclemcp-db`; the `plsql-mcp` adapter maps that connection into the `plsql-catalog` `OracleConnection` trait for catalog-shaped loaders. Supports TNS aliases, EZConnect, Oracle Wallet, `~/.dbtools` saved profiles, OCI IAM tokens, and mTLS to the extent the `oraclemcp-db` / `oracledb` backend supports them. First-class interop target: reuse SQLcl / SQL Developer `~/.dbtools` connections verbatim so switching costs stay low. No `plsql-mcp`-specific credential store; no novel auth surface.

**Credential storage.** `plsql-mcp` never persists credentials itself. Credentials live where they always live: in TNS / wallet / dbtools / OCI IAM. The MCP server reads what's already on the developer's machine. Matches the existing `oracle-mcp/server.py` pattern; keeps the security posture compatible with regulated shops (the credential surface is the developer's existing SQL Developer / SQL*Plus install, not a new attack surface).

**Audit baseline.** Every live-DB tool call:

- Tags the Oracle session via `DBMS_APPLICATION_INFO.SET_MODULE('plsql-mcp', $tool_name)`
- Sets `V$SESSION.ACTION` to the agent model name (surfaced via MCP `_meta.session.client_info`)
- Embeds `/* plsql-mcp $tool $session-id $agent-model */` as a comment on every emitted SQL statement
- For guarded writes / DDL / escalation, appends a signed, hash-chained out-of-band JSONL record through `oraclemcp-audit` before the Oracle execute call (`PLSQL_MCP_AUDIT_FILE` + `PLSQL_MCP_AUDIT_KEY`); without this signed sink the write path fails closed
- Doctor subcommand reports the guarded-write audit posture and points operators at `oraclemcp audit verify <PLSQL_MCP_AUDIT_FILE>` / `verify_records(...)`

Convention deliberately matches Oracle SQLcl MCP (`V$SESSION.MODULE='SQLcl-MCP'`) so DBAs reviewing audit logs see consistent vendor markers across MCP servers.

**Read-only-by-default safety guard.** Every live-DB session starts read-only. Write tools refuse with a structured error containing the remediation steps: *"call `enable_writes` first; this session is read-only by default per §13A.3 safety policy."* The session-level toggle does not bypass per-operation approval — destructive operations still require the `preview_sql` → `execute_approved` flow on top of write enablement.

**Named safety profiles.** Live-DB access is exposed through named safety profiles rather than raw integers:

- `static_only` — no live-DB tools available
- `inspect_only` — default when `live-db` is enabled; read-only tools only
- `ddl_guarded` — preview + approval flows available, direct writes still blocked
- `session_write_enabled` — temporary post-operator-confirmation state

`doctor` and `current_database` report the active profile. This borrows the useful operational idea from SQLcl's restrict levels without making users memorize `-R 0..4`.

**Per-operation approval flow.** Destructive operations follow a deterministic two-step pattern:

1. Agent calls `preview_sql(operation)` → returns DDL preview + single-use approval token (60s TTL default)
2. Agent (or operator) inspects via `read_patch_preview(token)`
3. Agent calls `execute_approved(token)` or the tool's `apply` mode with the token → executes the previewed DDL

Token is single-use, time-limited, and tied to the *exact* previewed DDL byte-for-byte. Re-running `preview_sql` invalidates prior tokens. Same flow as the workspace's existing `oracle-mcp/server.py`; preserves the brand promise that destructive operations are never accidental and never invisible.

**Permanently read-only connections.** A connection can be flagged `permanently_read_only = true` in `~/.plsql-mcp/connections.toml`. The hard guard refuses `enable_writes` and every write tool regardless of session state — operator confirmation cannot override it. Recommended for production database connections. Doctor subcommand prominently reports any connection without this flag set on a production-looking DSN (heuristic: hostname matches `*prod*`, `*production*`, or matches a configurable production allowlist).

**Driver dependency.** `plsql-mcp`'s normal `live-db` feature pulls in the published `oraclemcp-db` connection layer, which uses the pure-Rust `oracledb` stack. The default `plsql-mcp` binary, Docker image, and live-XE feature do not require or bundle Oracle Instant Client. The legacy thick `oracle` / ODPI-C catalog compatibility path was retired by C.6 after the differential gate passed; doctor reports the active live backend as `oraclemcp-db`.

**Boundary with the wider Track B Live-DB Oracle MCP.** v0.10 absorbs basic live-DB tools into `plsql-mcp`. What stays in Track B (separate project, out of scope here) is the *production-operations* surface: SIEM integration / external audit forwarders, OpenTelemetry distributed tracing, multi-tenant credential broker (federated SSO across many DBs), FedRAMP/HIPAA audit retention configuration, OCI IAM SSO federation, per-tenant rate limiting, fleet-visibility dashboard, compliance reporting. Those are operational features for fleet-wide deployment, not individual-developer agent use. §2.2 restates the boundary.

### 13A.4 Naming and discoverability

The crate / binary name is **`plsql-mcp`**, consistent with the rest of the `plsql-*` workspace. *"Oracle PL/SQL MCP server"* is the descriptive wording — used in README / docs / blog posts / GitHub topics, never as a top-level package name (to avoid Oracle® trademark exposure, per the D15 rejection of `PLOracle`). Discoverability comes through SEO content, awesome-mcp-server listings, and the official MCP servers index — not through squatting on the trademark.

**MCP server identity.** In Cursor / Claude Desktop configs, the server identifier is `"plsql"` (short, scope-honest, doesn't pretend to be an Oracle product). Logo/branding lands later under D15.

### 13A.5 Acceptance criteria

**Static-analysis surface:**

- `cargo install plsql-mcp` produces a working stdio MCP server on Linux x86_64, macOS aarch64, Windows x86_64
- A fresh Cursor / Claude Desktop / Codex CLI / Windsurf config pointing at `plsql-mcp` lists the full §13A.2 tool surface in `tools/list` — static-analysis, live-DB connectivity, and `change_tools` change-impact tools
- `tools/list` is identical for every user; no license key, no entitlement check, no fallback mode
- Every tool response includes a `meta.trust_block` field with the same payload shape as the CLI Trust Block (§1.5)
- Every tool response that contains uncertainty carries explicit `UnknownReason` + remediation hint
- The hero demo from §1.4 (DROP COLUMN `customers.legacy_segment`) runs end-to-end via MCP: an agent calls `what_breaks` on a synthetic-lab proposed diff and gets back the same report shape as the CLI emits, with Trust Block intact

**Live-DB surface:**

- Live-DB tools work against an Oracle XE 23ai container via the `make demo-oracle-xe` path (§6.2.8.1)
- `cargo install plsql-mcp --no-default-features` produces a binary with live-DB tools disabled; static-analysis tools still function; doctor reports the `live-db` feature is off
- With `live-db` enabled, doctor reports the `oraclemcp-db` backend and does not require Instant Client; static-analysis tools still function independently of live connection configuration
- If `~/.dbtools` contains saved SQLcl / SQL Developer connections, `list_connections` discovers them and `connect` can use them without copying credentials into a second store
- `doctor` and `current_database` report the active safety profile; default live-DB profile is `inspect_only`
- `enable_writes` refuses without an operator confirmation token; succeeds with one
- `enable_writes` refuses on a `permanently_read_only` connection regardless of confirmation token
- Every emitted SQL statement is verifiable in `V$SESSION.MODULE='plsql-mcp'` and carries the `/* plsql-mcp ... */` comment in `V$SQL.SQL_TEXT`
- The `preview_sql` → `execute_approved` flow rejects expired tokens, mismatched tokens, and tokens whose preview DDL was modified
- Prompt-injection sanitization test (K18 mitigation): a synthesized row value containing MCP-injection markers (e.g. `</tool_response><tool_call>...`) is scrubbed in the `query` response and replaced with a benign placeholder + an `UnknownReason::ResponseSanitized` note
- Cross-schema write operation requires interactive schema-name confirmation that exactly matches the target schema string
- Hero demo (§1.4 DROP COLUMN) runs end-to-end against a real Oracle XE container via the live-DB tools (`connect` + `query` + `compile_with_warnings` + `patch_package` + the `change_tools` `what_breaks` chained in the same agent session)

**Cross-surface:**

- Doctor subcommand (`plsql-mcp doctor`) passes a health check on a fresh install: protocol version negotiated, transport functional, engine cache reachable, `live-db` feature build-status, live backend (`oraclemcp-db` over `oracledb`), active safety profile, default write-posture, `permanently_read_only` connections found in config
- The `_meta.session.client_info` field is propagated from MCP client into `V$SESSION.ACTION` so DBAs auditing live-DB activity see *which* agent ran *which* tool
- `docs/integrations/live-db/sqlcl-compatibility-matrix.md` ships with a dated feature matrix covering overlap, intentional divergence, and current capability gaps versus Oracle SQLcl MCP; refreshed before each release so market-facing copy does not drift

### 13A.6 Bead seeds — MCP adapter surface

Layer-3 foundation work (depends on Layer 2.5 engine completion):

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-MCP-001` | Author `plsql-mcp` crate skeleton: Cargo.toml, MCP protocol library selection, module structure, `--robot-json` and doctor subcommand wiring. Depends only on Layer-0 engine *stubs* (ENG-000) so the crate compiles; concrete engine integration happens in the per-tool beads below (which depend on the full engine impl) | ENG-000 | S |
| `PLSQL-MCP-002` | Implement MCP stdio transport + protocol handshake + tools/list + tools/call dispatch | MCP-001 | M |
| `PLSQL-MCP-003` | Implement foundation tool: `analyze_project` (loads engine, runs pipeline, returns AnalysisRun summary) | MCP-002 + ENG-004 | M |
| `PLSQL-MCP-004` | Implement foundation tools: `parse_file`, `get_symbol`, `compile_check`, `inspect_profile` | MCP-003 | M |
| `PLSQL-MCP-005` | Implement foundation tools: `find_callers`, `find_callees`, `get_dependencies` | MCP-003 + DEP-014 | M |
| `PLSQL-MCP-006` | Implement foundation tools: `dynamic_sql_evidence`, `completeness_report`, `doc_lookup` | MCP-003 + FLOW-005 + FACT-005 + DOC-008 | M |
| `PLSQL-MCP-007` | Wire Trust Block (§1.5) into every MCP response as `meta.trust_block` field | MCP-006 + ENG-005 | M |
| `PLSQL-MCP-008` | Implement optional `--listen <host:port>` TCP transport for remote agents | MCP-002 | S |
| `PLSQL-MCP-009` | Integration test: drive `plsql-mcp` from a scripted MCP client against the synthetic lab (§6.2.8.1); golden-snapshot every tool response | MCP-007 + LAB-005 | M |
| `PLSQL-MCP-010` | Doctor subcommand: protocol version, transport health, engine cache reachable, AnalysisProfile sanity | MCP-007 | S |
| `PLSQL-MCP-011` | Cursor / Claude Desktop / Devin / Windsurf integration walkthroughs in `docs/integrations/` | MCP-009 | M |
| `PLSQL-MCP-012` | Submit `plsql-mcp` to the official MCP servers index + awesome-mcp lists | MCP-011 | S |

Layer-3 live-DB foundation work (depends on `plsql-catalog` OracleConnection, NOT on the full engine — these can ship earlier per D19):

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-MCP-LIVE-001` | Author `plsql-mcp` `live-db` Cargo feature flag; default-on for binary, optional for library; doctor reports `live-db` build-status and the `oraclemcp-db` live backend | MCP-001 + CAT-003 | S |
| `PLSQL-MCP-LIVE-002` | Implement connection management tools (`list_connections`, `connect`, `disconnect`, `current_database`, `switch_database`) reusing `plsql-catalog`'s `OracleConnection` trait and first-class `~/.dbtools` interop | MCP-LIVE-001 + CAT-003 | M |
| `PLSQL-MCP-LIVE-003` | Implement audit baseline: `DBMS_APPLICATION_INFO.SET_MODULE`, `V$SESSION.ACTION` from MCP client_info, `/* plsql-mcp $tool $session-id $agent-model */` statement marker, optional audit-table append | MCP-LIVE-002 | M |
| `PLSQL-MCP-LIVE-004` | Implement `query` tool with structured row output, column metadata, LOB handling, and K18 prompt-injection sanitization (scrub MCP / tool-call markers in row values, emit `UnknownReason::ResponseSanitized` note) | MCP-LIVE-003 | M |
| `PLSQL-MCP-LIVE-005` | Implement `list_objects` with structured type / name-pattern / schema filters; pages results with cursor token for large estates | MCP-LIVE-002 + CAT-004 | M |
| `PLSQL-MCP-LIVE-006` | Implement `describe_table`, `describe_view`, `describe_trigger`, `describe_index` with structured (not free-text) responses including columns, constraints, indexes, comments, partition info | MCP-LIVE-005 + CAT-004 + CAT-015 | M |
| `PLSQL-MCP-LIVE-007` | Implement `get_object_source`, `get_clob` (with K18 sanitization), `get_errors` (structured `USER_ERRORS` / `ALL_ERRORS`) | MCP-LIVE-002 + CAT-004 + CAT-015 | M |
| `PLSQL-MCP-LIVE-008` | Implement named safety profiles (`inspect_only` default, `ddl_guarded`, `session_write_enabled`) + read-only-by-default session state + `enable_writes` requiring operator confirmation token + `disable_writes` | MCP-LIVE-002 | M |
| `PLSQL-MCP-LIVE-009` | Implement `permanently_read_only` connection-level config flag in `~/.plsql-mcp/connections.toml`; hard guard refuses `enable_writes` regardless of confirmation token | MCP-LIVE-008 | S |
| `PLSQL-MCP-LIVE-010` | Implement `compile_with_warnings` (`ALTER ... COMPILE` with `PLSQL_WARNINGS = ENABLE:ALL`); structured warning categorization (severe / informational / performance) — uses `OracleConnection` directly; no PL/Scope dependency | MCP-LIVE-008 | M |
| `PLSQL-MCP-LIVE-011` | Implement `preview_sql` + `read_patch_preview`: single-use 60s-TTL approval token tied to exact DDL bytes; invalidated by any new `preview_sql` call | MCP-LIVE-008 | M |
| `PLSQL-MCP-LIVE-012` | Implement `patch_package` (targeted REPLACE-based package edit, `dry-run` / `apply` modes; mirrors a proven production Oracle MCP `patch_package` flow) | MCP-LIVE-011 + CAT-015 | M |
| `PLSQL-MCP-LIVE-013` | Implement `patch_view` (same flow as `patch_package`) | MCP-LIVE-012 | S |
| `PLSQL-MCP-LIVE-014` | Implement `create_or_replace` (full DDL deployment under per-operation approval) | MCP-LIVE-011 | M |
| `PLSQL-MCP-LIVE-015` | Implement `execute_approved` (run previously-previewed statement under token) and `deploy_ddl` (lock-free via `DBMS_SCHEDULER`, a one-shot `PLSQL_BLOCK` scheduler job) | MCP-LIVE-014 | M |
| `PLSQL-MCP-LIVE-016` | Implement interactive schema-name confirmation for cross-schema write operations (operator must type the schema name verbatim) | MCP-LIVE-014 | S |
| `PLSQL-MCP-LIVE-017` | Doctor subcommand: `live-db` feature build-status, `oraclemcp-db` backend, write-posture per connection, `permanently_read_only` audit, production-DSN heuristic warnings | MCP-LIVE-008 + MCP-LIVE-009 | M |
| `PLSQL-MCP-LIVE-018` | Integration test: every live-DB tool E2E against Oracle XE 23ai container; chained-flow test (preview → execute_approved); refusal tests (read-only-default, expired token, mismatched token, `permanently_read_only` block) | MCP-LIVE-007 + MCP-LIVE-016 + CAT-008 + LAB-007 | L |
| `PLSQL-MCP-LIVE-019` | Hero demo (§1.4 DROP COLUMN) end-to-end via live-DB tools against the synthetic-lab Oracle XE deployment; golden-snapshot the full agent transcript | MCP-LIVE-018 + LAB-006 | M |
| `PLSQL-MCP-LIVE-020` | Per-platform live-DB integration walkthroughs in `docs/integrations/live-db/{linux,macos,windows}.md` covering thin-driver setup, wallet / connect-string setup, `permanently_read_only` examples, Claude Code / Cursor / Codex CLI config snippets | MCP-LIVE-017 | M |
| `PLSQL-MCP-LIVE-021` | Author and maintain `docs/integrations/live-db/sqlcl-compatibility-matrix.md`: dated overlap / divergence / capability-gap matrix versus Oracle SQLcl MCP so README, docs, and sales copy stay source-backed | MCP-LIVE-020 | S |

Change-impact tools (depends on Layer 4 lineage + Layer 5 CICD completion). These ship in `plsql-mcp` itself, in module `change_tools`; the `PLSQL-MCP-PRO-*` bead IDs are retained as immutable historical references:

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-MCP-PRO-001` | Add the `change_tools` module to `plsql-mcp` | MCP-007 | M |
| `PLSQL-MCP-PRO-002` | Register the `change_tools` tools in `ToolRegistry` so they advertise in `tools/list` alongside the static-analysis and live-DB tools | MCP-PRO-001 | M |
| `PLSQL-MCP-PRO-003` | Implement change-impact tools: `what_breaks`, `classify_change`, `compare_oracle_deps` | MCP-PRO-002 + LIN-002 + LIN-016 | M |
| `PLSQL-MCP-PRO-004` | Implement change-impact tools: `sarif_scan`, `orphan_candidates`, `explain_lifecycle` | MCP-PRO-002 + SAST-003 + LIN-021 + CICD-013 | M |
| `PLSQL-MCP-PRO-005` | Implement change-impact tools: `release_gate`, `recompile_plan` | MCP-PRO-002 + CICD-002 + CICD-006 | M |
| `PLSQL-MCP-PRO-006` | Integration test: hero demo (§1.4 DROP COLUMN scenario) end-to-end via MCP against the synthetic lab; golden snapshot the `what_breaks` payload | MCP-PRO-003 + LAB-006 | M |
| `PLSQL-MCP-PRO-007` | Doctor subcommand: report `change_tools` availability and engine-dependency build status | MCP-PRO-002 | S |
| `PLSQL-MCP-PRO-008` | Document the `change_tools` surface in `docs/integrations/` | MCP-PRO-007 | M |

### 13A.7 Open questions

- **MCP-D1: license key format and offline validation.** Resolved as moot. The project is uniformly open-source under `Apache-2.0 OR MIT`; there is no license key, no activation, and no entitlement check. The whole `plsql-mcp` tool surface is available to everyone.
- **MCP-D2: model-context-protocol library choice.** rust-mcp-sdk if mature enough, else hand-rolled minimal MCP impl in `plsql-mcp` itself. **Recommendation:** evaluate at MCP-002 spike; if the ecosystem library is solid, take it; otherwise hand-roll (the protocol is small).
- **MCP-D3: how to expose the lab schema as a built-in MCP resource.** The MCP `resources/list` mechanism could let an agent enumerate the synthetic lab's source files for demos. **Recommendation:** ship as an opt-in `--enable-lab-resources` flag in `plsql-mcp`, not enabled by default (avoids surprising users who don't know they have lab content available).
- **MCP-D4: per-tool rate limiting / cost annotation.** Some tools (`what_breaks` on a large changeset, `compare_oracle_deps` on a 500k-LOC estate) are expensive. Should the MCP response include estimated cost / latency hints so agents can plan? **Recommendation:** yes — add `meta.cost_estimate` per tool response from the start; cheap to ship, prevents bad agent behavior later.
- **MCP-D5: live-DB driver backend.** Resolved for `plsql-mcp` by the 0.5.0 convergence: the normal `live-db` and `live-xe` features use the published `oraclemcp-db` layer over the pure-Rust `oracledb` stack. The legacy `oracle` / ODPI-C path was removed by C.6. Doctor reports which backend is in use.

---

## 14. Layer 4 — Lineage Engine

### 13.1 Purpose

Aggregate Layers 2's dependency graph into customer-facing impact analyses. Answer: "if I change X, what breaks?" "What reads/writes column Y?" "Show me the call chain from procedure A to table B." This is the flagship commercial product.

### 13.2 Core operations

| Operation | Input | Output |
|-----------|-------|--------|
| `impact(node)` | A schema object | Set of objects transitively affected by changes to it (downstream-impacted) |
| `dependencies(node)` | A schema object | Set of objects it transitively depends on (upstream-needed) |
| `callers(proc_or_fn)` | A procedure/function | Set of callers (direct + transitive) |
| `column-readers(col)` | A column | All places that read the column |
| `column-writers(col)` | A column | All places that write the column |
| `unsafe-paths(from, to)` | Two nodes | Set of paths between them that include opaque/dynamic edges |
| `recompile-order(set)` | A set of changing objects | Topologically sorted recompile order respecting invalidation cascade |
| `classify-change(before, after)` | Old/new source or catalog snapshots | `SemanticChangeSet`: signature change, body change, DDL, column change, privilege change, synonym change, grant change, type change |
| `classify-rename(before, after, hints)` | Old/new model + optional rename hints (Git rename detection, explicit mapping, persistent IDs) | Candidate rename mappings with confidence; never silently merges |

**Column-level lineage precision tiers** (false precision is worse than `Unknown`; Oracle SQL has too many ways to make column mapping unreliable — `SELECT *`, `NATURAL JOIN`, `USING`, views over views, MODEL, hierarchical queries, PIVOT/UNPIVOT, JSON functions, dynamic SQL, synonyms, editioning views):

| Tier | Meaning |
|------|---------|
| `ExactColumnLineage` | Deterministic source → target column mapping |
| `ExpressionColumnLineage` | Target derives from an expression over known input columns |
| `TableScopedColumnUnknown` | Table known, specific column unknown |
| `DynamicColumnUnknown` | Dynamic SQL or runtime projection prevents static mapping |
| `UnsupportedSqlShape` | Parser recognized SQL, but the semantic extractor does not support this construct yet |
| `explain(edge_or_path)` | Edge/path ID | Human-readable proof of why this relationship exists: span, statement, resolution path, synonym chain, catalog facts, confidence, dynamic-SQL evidence |
| `compare-oracle-deps(snapshot)` | Our depgraph + Oracle `ALL_DEPENDENCIES` rows | Delta report: what Oracle sees vs what we see vs why they differ. Demo-grade customer artifact showing engine value beyond Oracle's own dictionary |

Each result includes provenance (which edges contributed) and confidence (aggregated from edge confidences along the path).

### 13.3 What-breaks report

Given a proposed change (a DDL statement or a procedure body change), emit a structured report:

```
Change: DROP COLUMN customers.legacy_segment

Direct impact (confidence: high):
  - VIEW v_active_customers references legacy_segment
  - TRIGGER trg_customer_audit logs legacy_segment
  - PACKAGE customer_pkg.classify() reads legacy_segment

Transitive impact (confidence: high):
  - PACKAGE billing_pkg.compute_bill() calls customer_pkg.classify()
  - REPORT job_monthly_summary uses v_active_customers

Uncertain impact (confidence: low — dynamic SQL):
  - PACKAGE legacy_reports.run_report may reference legacy_segment via EXECUTE IMMEDIATE (string template includes 'legacy_segment')

Total objects affected: 6 high-confidence + 1 low-confidence
Recommended action: review the uncertain reference; coordinate with billing team for the transitive chain.
```

### 13.4 Output formats

- Human-readable terminal report (miette-style with clickable file paths)
- JSON (machine-consumable; `--robot-json`)
- HTML report (standalone; embeds the impact subgraph as SVG)
- GraphML (for opening in Gephi / yEd)

### 13.5 Acceptance criteria

- For every operation in §13.2, end-to-end test against synthetic corpus produces expected results
- Confidence scoring aggregates correctly (path confidence = min(edge confidences) by default; configurable)
- HTML report renders correctly with embedded SVG impact subgraph
- `plsql-lineage what-breaks` accepts **all of the following** and classifies them into a `SemanticChangeSet` before computing impact:
  - a Git diff (`--git-diff <range>`)
  - a before/after directory pair (`--before <dir> --after <dir>`)
  - a DDL changeset file (`--ddl <file>`)
  - a catalog snapshot diff (`--catalog-diff <before.json> <after.json>`)
- The structured report distinguishes semantic-change-kind (signature vs body vs DDL vs privilege vs column vs synonym) — different kinds produce different downstream impact sets
- Every lineage report includes a compact **completeness block** drawn from `CompletenessReport`: parse quality, catalog availability, wrapped units, unresolved refs, dynamic SQL sites, opaque sites, DB-link edges
- `plsql-lineage explain --edge <id>` prints provenance + evidence: source span, SQL/PLSQL statement, resolution strategy, catalog facts, confidence, dynamic-SQL evidence where relevant
- Doctor subcommand: report graph completeness statistics on corpus

### 13.6 Bead seeds — Lineage

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-LIN-000` | Define `SemanticChangeSet` model: DDL, signature, body, privilege, synonym, column, type, grant changes | Layer 2 | M |
| `PLSQL-LIN-001` | Define `LineageQuery`, `LineageResult`, `Confidence` types | Layer 2 | M |
| `PLSQL-LIN-002` | Implement `impact(node)` traversal with confidence aggregation | LIN-001 | M |
| `PLSQL-LIN-003` | Implement `dependencies(node)` (reverse traversal) | LIN-001 | M |
| `PLSQL-LIN-004` | Implement `callers(proc)` and `column-readers/writers` | LIN-002 | M |
| `PLSQL-LIN-005` | Implement `unsafe-paths(from, to)` for dynamic-SQL audit trails | LIN-002 | M |
| `PLSQL-LIN-006` | Implement `recompile-order(set)` (topological sort respecting Oracle invalidation) | LIN-002 | M |
| `PLSQL-LIN-007` | Implement `what-breaks --change <file>` parser (accepts DDL diffs and procedure body diffs) | LIN-002 + LIN-000 + Layer 1 | L |
| `PLSQL-LIN-007A` | Implement Git-diff / before-after-directory / catalog-snapshot-diff change classifier; emit `SemanticChangeSet` | LIN-000 + Layer 1 | L |
| `PLSQL-LIN-008` | Implement HTML report with embedded SVG impact subgraph | LIN-002 + Layer 0 | M |
| `PLSQL-LIN-009` | Implement JSON output for all operations (`--robot-json`) | LIN-002 + Layer 0 | S |
| `PLSQL-LIN-010` | Implement GraphML export of impact subgraph | LIN-002 + Layer 0 | S |
| `PLSQL-LIN-011` | Doctor subcommand: graph completeness + low-confidence inventory | LIN-002 | S |
| `PLSQL-LIN-012` | End-to-end test: 50-package synthetic corpus; verify `impact(table) ⊇ expected_set` | LIN-007 | M |
| `PLSQL-LIN-013` | Document the lineage engine at `docs/components/lineage.md` (300+ lines) including the confidence model, all operation semantics, and example reports | LIN-007 | M |
| `PLSQL-LIN-014` | Implement `explain` command for edges, nodes, and paths (reuses DEP-015 plumbing in a customer-facing lineage shape) | LIN-002 + DEP-015 | M |
| `PLSQL-LIN-015` | Implement `classify-rename` with hints (Git rename detection, explicit mapping, persistent-ID linking); candidate mappings with confidence | LIN-000 + LIN-002 | M |
| `PLSQL-LIN-016` | Implement `compare-oracle-deps` customer report from depgraph + `ALL_DEPENDENCIES` cross-check | DEP-014 + LIN-002 | M |
| `PLSQL-LIN-017` | Add "Oracle sees / engine sees / uncertain" report section to HTML lineage output | LIN-016 + LIN-008 | M |

### 13.8 Orphan Candidates Report

A productized lineage report that surfaces packages, procedures, functions, tables, views, and synonyms with **no incoming static reference edges** in the dependency graph. Executive-friendly artifact for cleanup, security posture, and Oracle-license-cost reduction. Sold as part of Change Impact Pro (§1.4), not standalone.

**Confidence tiers are mandatory.** Static incoming-edge absence does NOT prove dead code in Oracle. The following can all bypass source-visible edges and create false-positive "orphan" findings:

- External callers: Java / .NET / Python / Node applications invoking PL/SQL via JDBC / ODP.NET / oracledb
- APEX pages, processes, validations, dynamic actions, plugins, REST sources
- DBMS_SCHEDULER jobs (modeled by the engine but easy to misconfigure)
- DB-link callers from other schemas / databases
- Dynamic SQL with names assembled from variables / catalog lookups
- Public synonyms or grants to roles consumed by unknown parties
- Ad-hoc reporting tools, ETL platforms (Informatica, ODI, DataStage), BI tools (OBIEE, Tableau, Power BI)
- Runtime-resolved invocations under invoker rights with roles enabled

The report **never** says *"safe to drop tomorrow."* Every candidate carries an explicit confidence tier and a recommended observation window before any deletion decision:

| Tier | Definition | Recommended next step |
|------|------------|------------------------|
| **High confidence orphan** | No static edges + no DBMS_SCHEDULER job + no public synonym + no GRANT TO PUBLIC + no DB-link references + completeness profile shows: catalog snapshot available, no opaque dynamic SQL in the entire estate, no wrapped units referencing this surface | 30-day production observation: enable AUDIT or fine-grained DBMS_FGA; if zero invocations recorded, then propose for removal |
| **Medium confidence orphan** | No static edges, BUT one or more of: dynamic SQL evidence inconclusive, public synonym present, GRANT TO PUBLIC, DB-link reachable, wrapped units in scope | 60-day observation including AUDIT + application-log review + stakeholder confirmation (app teams, scheduled-batch owners, BI/ETL owners). Do NOT propose for removal until confirmed |
| **Low confidence / requires manual review** | No static edges, but completeness profile is poor: missing catalog metadata, opaque dynamic SQL elsewhere in the call graph, missing package bodies, DB-link to inaccessible remote schema, edition-based redefinition active | 90-day observation, manual triage, treat as a hint that the dependency graph itself is incomplete — provide more inputs and re-run before any deletion conversation |

The HTML / JSON / Markdown outputs MUST partition findings by tier. The default view shows High + Medium; Low is collapsed behind a "show low-confidence orphans" toggle (the customer can hide it but not by default — this is the same UX rule as the Trust Block).

**Required content for every orphan finding:**

- Identifier (schema-qualified, with `LogicalObjectId`)
- Last DDL timestamp from catalog (`LAST_DDL_TIME`)
- LOC + key signature (helps the reviewer prioritize)
- Whether it has incoming references that were classified as `Unknown` (and why)
- All grants on the object — TO PUBLIC, TO named roles, TO named users
- Synonym map (public + private synonyms pointing at it)
- DBMS_SCHEDULER job references (engine-modeled)
- DB-link references reaching this object
- AUDIT recommendation: ready-to-paste `AUDIT EXECUTE ON ...` statement for that confidence tier's observation window
- Remediation timeline: the exact "30-day / 60-day / 90-day next step" applicable to its tier

**Anti-pattern guards:**

- The report MUST NOT produce a single "X lines of dead code" headline number. Every aggregate count is partitioned by confidence tier.
- The report MUST NOT include a "drop script." It includes AUDIT-enablement statements; deletion scripts are an explicit out-of-scope feature for first release (a deletion script that runs on a real Oracle database is far higher liability than the report itself).
- The report's executive-summary section MUST include the Trust Block (§1.5) showing what would improve the confidence of every Low / Medium finding (provide catalog snapshot, enable PL/Scope, narrow dynamic-SQL allowlists, supply DB-link inventory, etc.).
- The report MUST NOT be advertised as a "find dead code" feature. It is advertised as *"surface unused-looking objects + the evidence you need to safely investigate them."*

**Why this exists.** Cleanup is the executive-friendly POC artifact — a CIO who sees *"we have 87 packages and 312 procedures with no static incoming references; here's the audit script to confirm and the 30/60/90-day path"* understands the value in 30 seconds. It also doubles as a security-posture artifact (orphan code is reachable by attackers but rarely reviewed) and an Oracle-license-cost reduction artifact (orphan tables in licensed feature usage). All of that follows naturally from lineage + the engine's existing UnknownReason taxonomy.

**Bead seeds — Orphan Candidates.** Append to §13.6 lineage beads.

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-LIN-018` | Define `OrphanCandidate` + `OrphanConfidenceTier` types in `plsql-output` | LIN-000 | M |
| `PLSQL-LIN-019` | Implement orphan detection: zero-incoming-edge query + grant/synonym/scheduler/DB-link augmentation | LIN-002 + LIN-016 | M |
| `PLSQL-LIN-020` | Implement confidence-tier classifier (High / Medium / Low) using `CompletenessReport` + augmentation signals | LIN-019 + facts gate | M |
| `PLSQL-LIN-021` | Implement HTML / Markdown / JSON report with mandatory tier partitioning + Trust Block + AUDIT statement generation | LIN-020 | M |
| `PLSQL-LIN-022` | Lab fixture: deliberately orphan-vs-not-orphan packages in `corpus/lab/` (L2 expansion) with golden expected report | LIN-021 + LAB-004 | M |
| `PLSQL-LIN-023` | Doctor check: orphan report freshness, observation-window expiry, audit-enablement recommendations consistency | LIN-021 | S |

### 13.9 Open questions

- **D12: column-level lineage in dynamic SQL** — when dynamic SQL builds a column name from a variable, do we report the column as `Unknown` or attempt enumeration? Recommend `Unknown` with the variable's value-set if statically inferrable (rare), else `Unknown`.
- **D14: live workload correlation** — at first close, lineage is purely static. Customers will eventually ask for "of the impacted objects, which are actually hot in production?" This requires integrating with AWR/ASH and is its own product layer; defer. Note: orphan-candidate observation-window AUDIT recommendations are the closest in-plan touchpoint with eventual AWR/ASH correlation — the data structures should not preclude it.

---

## 15. Layer 5 — CI/CD Recompilation Cascade

### 15.1 Purpose

Pre-deploy tooling for Oracle environments. Given a proposed change set (a directory of DDL + PL/SQL files representing what's about to be deployed), predict which existing objects will invalidate, in what order they must be recompiled, and which compile failures would block the deployment. Emit a CI-friendly report and a deployment script.

### 15.2 Operations

| Operation | Description |
|-----------|-------------|
| `predict <changeset>` | Emit invalidation tree + recompile order. Modes: `source-only` (best-effort, no catalog), `catalog-aware` (recommended; uses a `CatalogSnapshot` matching the target environment), `live-snapshot` (extracts snapshot first, then predicts). Prediction must distinguish: package spec change, package body-only change, standalone procedure/function signature change, table additive DDL, table destructive DDL, type evolution, synonym retargeting, grant/revoke, editioned object change, materialized view refresh-affecting change. |
| `explain-lifecycle <changeset>` | Explain Oracle lifecycle effects: invalidation, reauthorization, edition impact, package state discard, synonym retargeting, grant/revoke runtime risk, materialized-view refresh implications |
| `verify <changeset>` | Apply the changeset only against an **isolated verification target**: scratch schema, cloned PDB, disposable container, or explicitly-approved sandbox. Verify every dependent recompiles cleanly. **Never promises transaction rollback for DDL** — Oracle DDL implicitly commits before and after execution. |
| `plan <changeset>` | Emit an idempotent deployment script (DDL + COMPILE statements in dependency order) |
| `gate <changeset>` | CI gate: exits 0 if predicted invalidation is acceptable per configured policy, non-zero otherwise |

### 15.3 Connection requirements

Static operations (`predict`, `plan`) can run **source-only**, but source-only mode is explicitly best-effort. Reliable prediction requires a `CatalogSnapshot` matching the target environment — current object status, dependencies, edition, grants, synonyms, types not present in the source repo. `predict` modes:

- `source-only` — labels missing catalog facts as uncertainty; useful for fast pre-commit feedback
- `catalog-aware` — uses a `CatalogSnapshot`; reports higher completeness
- `live-snapshot` — extracts a fresh snapshot before predicting

Verification operations that execute DDL require an **isolated target** (scratch schema, cloned PDB, disposable container). Oracle DDL implicitly commits, so `verify` MUST NOT run against production-like schemas unless the user explicitly passes `--dangerously-verify-in-place`. The tool refuses by default and the dangerous flag is gated behind an interactive confirmation that prints the connected schema name.

Connection uses the `oracle` crate (or `oracle-rs` if D16 selects it). Read-only DDL inspection for `predict` and `plan`; `verify` requires write access to the isolated target.

### 15.4 Acceptance criteria

- `predict --mode source-only` produces the expected invalidation set for a synthetic change scenario and explicitly labels missing-catalog uncertainty
- `predict --mode catalog-aware` uses a catalog snapshot and reports higher completeness
- `predict --mode live-snapshot` extracts a fresh snapshot and produces equivalent output to catalog-aware mode against the same DB
- `verify` against an Oracle XE 23ai container correctly identifies a deliberately-broken cascade
- `plan` emits a script that, when applied to a fresh DB, deploys the changeset successfully
- `gate` integrates with GitHub Actions and GitLab CI (example workflows in `examples/ci/`)

### 15.5 Bead seeds — CI/CD

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-CICD-001` | Define `ChangeSet`, `InvalidationPrediction`, `DeploymentPlan` types | Layer 4 | M |
| `PLSQL-CICD-002` | Implement `predict <changeset>` using lineage `impact()` + Oracle-specific invalidation rules | CICD-001 + Layer 4 | M |
| `PLSQL-CICD-003` | Implement `plan <changeset>` emitting topologically-sorted DDL + recompile order | CICD-002 | M |
| `PLSQL-CICD-004` | Implement Oracle connection layer (read-only DDL inspection via `oracle` crate) | CICD-001 | M |
| `PLSQL-CICD-005` | Implement `verify <changeset>` against scratch schema / disposable Oracle container; **no rollback guarantee** (DDL implicitly commits) | CICD-004 | L |
| `PLSQL-CICD-005A` | Hard safety guard: refuse in-place DDL verification unless `--dangerously-verify-in-place` + interactive confirmation of connected schema name | CICD-005 | S |
| `PLSQL-CICD-006` | Implement `gate <changeset>` with policy file (`.plsql-cicd-policy.toml`) | CICD-002 | M |
| `PLSQL-CICD-007` | Author GitHub Actions example workflow in `examples/ci/github-actions.yml` | CICD-006 | S |
| `PLSQL-CICD-008` | Author GitLab CI example workflow | CICD-006 | S |
| `PLSQL-CICD-009` | Doctor subcommand: report on a customer's changeset health | CICD-002 | S |
| `PLSQL-CICD-010` | Integration test: synthetic changeset against Oracle XE 23ai container; verify predict→plan→apply→verify cycle | CICD-005 | M |
| `PLSQL-CICD-011` | Implement prediction modes: `source-only`, `catalog-aware`, `live-snapshot`; each mode emits its completeness profile | CICD-002 + CAT-004 | M |
| `PLSQL-CICD-012` | Implement Oracle lifecycle classifier: spec/body, type evolution, grant/revoke, synonym retarget, editioned-object change, materialized-view effects | CICD-001 + LIN-000 + CAT-014 | L |
| `PLSQL-CICD-013` | Implement `explain-lifecycle` report with evidence and safety warnings | CICD-012 | M |

### 15.7 PR integration (CI templates, not a hosted GitHub App)

The CI/CD cascade's daily-visible surface is **pull-request integration**: surfacing blast radius, recompile-order risk, dynamic-SQL evidence, and SAST findings on every PR that touches Oracle code. This is how the commercial nucleus (§1.4) becomes visible in the developer's actual workflow instead of being a tool someone runs out-of-band.

**Constraint:** the implementation MUST preserve the regulated / on-prem / no-telemetry posture (R17). Hosted GitHub Apps (multi-tenant SaaS over OAuth, cloud-stored analysis state, GitHub-side event ingress) are **explicitly out of scope** — they violate the trust posture and lock the founder into multi-tenant operations no solo founder should be running.

**What ships at GA.** Three artifacts, all self-hosted by the customer:

1. **`plsql gate --pr-comment-json`** output mode on the existing `gate` operation (§15.14.2). Emits a single structured JSON payload describing every finding that a PR-comment poster can render — keyed by file path, line range, severity, confidence tier, and remediation hint. Stable schema in `plsql-output`, versioned per R5.
2. **Reference CI templates** committed under `examples/ci/` and published as a separate Apache-2.0 repo `plsql-intelligence/ci-templates` referenced from the docs:
   - `.github/workflows/plsql-gate.yml` — GitHub Actions workflow runnable as-is. Uses `plsql gate --pr-comment-json | plsql post-pr-comment` (see #3 below). Runs entirely on the customer's runner.
   - `.gitlab-ci.yml` — GitLab CI equivalent with the same data flow. MR notes via the project's own access token.
   - `bitbucket-pipelines.yml` — minimal Bitbucket equivalent (lower priority).
   - `jenkins/Jenkinsfile.groovy` — for shops on Jenkins, including the on-prem regulated buyers most likely to want this.
3. **`plsql post-pr-comment`** — a tiny self-hosted comment poster shipped as a subcommand of the same `plsql` binary. Takes the `--pr-comment-json` payload + a customer-supplied token (`GITHUB_TOKEN`, `GITLAB_TOKEN`, etc.) on the CI runner, posts/updates the PR comment, exits cleanly. No outbound call from this host except to the customer's own VCS API. No telemetry. No third-party dependencies beyond the standard `oracle`/`reqwest` chain already used elsewhere.

**Required PR-comment content** (driven by the commercial nucleus + Trust Block):

- **Header:** Trust Block (§1.5) collapsed to a one-liner: *"Parsed 94% clean • 7 opaque dynamic-SQL sites • catalog snapshot age 3h • exact column lineage 72%."* Full Trust Block expandable via `<details>`.
- **Section 1: Blast radius.** `what-breaks` summary for the proposed diff — direct + transitive impact counts, the top 5 most-impacted objects, recompile order summary, dynamic-SQL evidence for any uncertain edges.
- **Section 2: Release gate verdict.** Pass / fail per the policy file (`.plsql-cicd-policy.toml`). When failing, an explicit list of which thresholds were exceeded.
- **Section 3: SAST findings on the changed surface only.** Frozen rule pack version, finding count by severity, suppression syntax inline.
- **Section 4: Recompile plan.** Topologically-sorted DDL + COMPILE statements that would land cleanly. Optional — toggled per-repo.
- **Section 5: "What would improve confidence?"** Surfaces the Trust Block's remediation hints inline. *"Provide a catalog snapshot to drop column-lineage Unknown from 19% to <5%."*

PR comments are **idempotent** — re-running the gate updates the same comment instead of stacking. The poster identifies its own comments via a stable HTML marker.

**Explicitly out of scope for GA** (recorded as decided non-goals — not future work for this plan):

- Hosted GitHub App / GitLab App with multi-tenant storage
- OAuth-based "install on every repo in the org" UX
- A SaaS dashboard aggregating findings across PRs
- Webhook-driven event ingress (GitHub webhook → our server)
- Any flow that requires inbound traffic to founder-operated infrastructure
- Cloud analysis state ("upload your Oracle code to us, we'll analyze")

**Why a CI-template approach beats a hosted app.** The buyer (regulated Oracle shop) can install this in a single PR to their own infra repo. No procurement of a new SaaS vendor. No incremental security review beyond what the existing `plsql` binary already required. Same trust posture as the rest of the product. The poster runs as the customer's CI; comments come from the customer's own bot account (`actions-bot`, `gitlab-ci-token`, etc.) — not from a third-party service.

**Bead seeds — PR integration.** Append to §14.5 CICD beads.

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-CICD-014` | Add `--pr-comment-json` output mode to `gate` operation; stable schema in `plsql-output` | CICD-006 | M |
| `PLSQL-CICD-015` | Implement `plsql post-pr-comment` subcommand (GitHub + GitLab adapters) | CICD-014 | M |
| `PLSQL-CICD-016` | Idempotent comment update logic with stable HTML marker | CICD-015 | S |
| `PLSQL-CICD-017` | `.github/workflows/plsql-gate.yml` reference workflow | CICD-015 | S |
| `PLSQL-CICD-018` | `.gitlab-ci.yml` reference workflow | CICD-015 | S |
| `PLSQL-CICD-019` | `Jenkinsfile.groovy` reference pipeline | CICD-015 | S |
| `PLSQL-CICD-020` | `plsql-intelligence/ci-templates` companion repo (Apache-2.0) + docs cross-links | CICD-017 + CICD-018 | S |
| `PLSQL-CICD-021` | Hero-demo PR-integration walkthrough on the synthetic lab (§6.2.8.1) | CICD-020 + LAB-006 | M |
| `PLSQL-CICD-022` | Doctor check: PR-integration health (token valid, last comment posted, payload schema version) | CICD-016 | S |

### 15.8 Open questions

- **D13: Liquibase / Flyway interop** — should the deployment plan emit a Liquibase-compatible changelog, or is the native script enough? Recommend: native script first; Liquibase compatibility is a follow-on integration with low marginal value.

---

## 16. Out of scope — Referential-Integrity Subsetting (separate future plan)

### 16.1 Purpose `[OUT OF SCOPE — ROUTED TO A SEPARATE FUTURE PLAN]`

This section is retained as a **conceptual placeholder** so the future subsetter idea is not lost; the component itself is **out of scope** of this plan. Its entries are not bead seeds for this plan and **must not be converted by `beads-workflow`**. The future subsetter plan will define its own bead seeds with its own refinement rounds.

The reason for routing it elsewhere: subsetting is its own product with its own customer profile (dev/test extraction), its own competitive landscape (Tonic, Delphix, K2View), and its own brutal complexity (FK cycles, self-referential tables, identity columns, sequences, triggers, LOBs, partitions, temp tables, huge data volumes, legal/privacy posture). Shipping it with stub masking would damage the first product's credibility. It deserves its own plan with its own refinement rounds.

The conceptual purpose remains for reference: given a seed (one or more rows in a table), extract a referentially-consistent subset of an Oracle database suitable for dev/test environments. Walk FK relationships, package dependencies, and configurable "soft references." Emit `INSERT` scripts or a data pump bundle.

### 16.2 Soft-reference handling

Real-world Oracle schemas frequently have references that aren't expressed as FKs:

- A column named `customer_id` in many tables, referencing `customers.id` (but no FK declared)
- A status column with values referenced by code in a `code_lookup` table
- Polymorphic associations (one column holds the type, another holds the ID)

Subsetter supports a `relationships.toml` file with explicit soft-reference rules:

```toml
[[soft_reference]]
from_table = "audit_log"
from_column = "customer_id"
to_table = "customers"
to_column = "id"
required = false

[[polymorphic]]
type_column = "audit_log.entity_type"
id_column = "audit_log.entity_id"
mappings = [
  { type_value = "CUSTOMER", target_table = "customers", target_column = "id" },
  { type_value = "ORDER", target_table = "orders", target_column = "id" },
]
```

The lineage engine can suggest soft-reference candidates by inspecting PL/SQL business logic.

### 16.3 Masking hooks

**Do not ship a dev/test extraction tool with masking presented as a stub.** First public subsetter release must either:

1. integrate with a real masking engine (BYO via well-defined plug-in points), or
2. require an explicit BYO masking command in the workflow, or
3. clearly label output as **non-anonymized and unsafe for lower environments** with a refusal-by-default that requires an explicit confirmation flag.

A `masking-hooks.toml` config defines per-column transformations using a simple DSL (`hash`, `null`, `constant`, `format-preserving`, `synthetic-from-corpus`). The DSL surface is part of the public spec but the implementations are an explicit product decision when this future product gets its own plan.

### 16.4 Output formats

- `INSERT` statements in dependency order
- Oracle Data Pump bundle (impdp/expdp parameter file generation)
- Schema-only diff (DDL to create the target schema if missing)
- Subset statistics (row counts per table, total bytes estimated)

### 16.5 Acceptance criteria

- Given Oracle HR sample schema as input, a seed `employees.employee_id = 100`, produce a referentially-complete subset that includes the employee's department, manager, country, region — without breaking FKs
- Generated `INSERT` script applies cleanly against a fresh HR schema
- Soft-reference walking demonstrably catches non-FK dependencies in the synthetic test corpus
- Doctor subcommand: report subset statistics + missing-reference inventory

### 16.6 Future subsetter work items — NOT converted in this plan

The entries below are **conceptual references** for the separate future subsetter plan. They are not bead seeds for `beads-workflow` to consume; they exist only so the design conversation does not have to restart from zero when that plan is opened.

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-SUB-001` | Define `SubsetPlan`, `SeedSpec`, `RelationshipRule` types | Layer 4 | M |
| `PLSQL-SUB-002` | Implement FK walker using lineage + Oracle metadata | SUB-001 + Layer 4 | M |
| `PLSQL-SUB-003` | Implement soft-reference config loader (`relationships.toml`) | SUB-001 | S |
| `PLSQL-SUB-004` | Implement soft-reference walker | SUB-003 | M |
| `PLSQL-SUB-005` | Implement polymorphic-association walker | SUB-003 | M |
| `PLSQL-SUB-006` | Implement INSERT-script emitter in dependency order | SUB-002 | M |
| `PLSQL-SUB-007` | Implement Data Pump parameter file generation | SUB-006 | M |
| `PLSQL-SUB-008` | Define masking-hook **interface only**; do not ship stub masking advertised as safe anonymization — the deferred-product status of subsetting requires real masking before public release | SUB-006 | M |
| `PLSQL-SUB-009` | Doctor subcommand: subset stats + missing-reference inventory | SUB-006 | S |
| `PLSQL-SUB-010` | Integration test: subset Oracle HR schema from a seed; apply to fresh DB; verify all FKs satisfy | SUB-006 | L |
| `PLSQL-SUB-011` | Implement soft-reference candidate suggester (uses Layer 4 lineage to flag likely soft references) | SUB-004 + Layer 4 | L |
| `PLSQL-SUB-012` | Document the subsetter at `docs/components/subset.md` (250+ lines) | SUB-010 | M |

### 16.7 Open questions

- **D9: masking strategy** — resolved for this plan as `[OUT-OF-SCOPE]`. The future subsetter plan must not ship public masking stubs as anonymization. Public subsetter release requires real masking, a verified BYO masking contract, or refusal-by-default for non-anonymized lower-environment extraction.

---

## 17. Oracle-specific semantic hazards

The engine must explicitly model or explicitly mark `Unknown` (per R13 + `UnknownReason` taxonomy) for each of the following Oracle features. This is a tracked-complexity inventory: every item here either has component support, has a known degradation path, or has a backlog bead.

| Hazard | Status | Component(s) | Notes |
|--------|--------|--------------|-------|
| Wrapped PL/SQL | Detect + `UnknownReason::WrappedSource` | `plsql-project`, `plsql-symbols` | Cannot analyze body; signature only |
| Edition-based redefinition | Detect + `UnknownReason::EditionedObject` | `plsql-catalog`, `plsql-symbols` | Catalog snapshot must record edition; analysis is per-edition |
| Invoker rights (`AUTHID CURRENT_USER`) | Modeled by `plsql-privileges` | `plsql-privileges`, SAST `SEC004` | Runtime authorization ambiguity surfaced as evidence |
| Definer rights (`AUTHID DEFINER`) | Modeled by `plsql-privileges` | `plsql-privileges` | Default; assumed unless `AUTHID CURRENT_USER` is declared |
| Private synonyms | Resolved by `plsql-symbols` strategy 4 | `plsql-symbols` | Catalog-aware |
| Public synonyms | Resolved by `plsql-symbols` strategy 4 | `plsql-symbols` | Catalog-aware |
| Database links | Recorded as `DbLink` edges; `UnknownReason::DbLinkRemoteObject` | `plsql-depgraph` | Out-of-database; never silently dropped |
| Conditional compilation (`$IF`/`$THEN`/`$ELSE`/`$END`) | **Preprocessed** by `plsql-project` using `AnalysisProfile::plsql_ccflags`; inactive regions retained as provenance | `plsql-project`, `plsql-parser` | Analysis is profile-specific; variant-analysis mode (parse all branches) is deferred |
| SQL\*Plus substitution variables | Handled by `plsql-project` splitter | `plsql-project` | Marked as opaque unless values supplied via config |
| Generated DDL | Detected; analyzed if a snapshot is available | `plsql-catalog` | Otherwise `UnknownReason::MissingCatalogObject` |
| Overloaded package routines | First-class nodes with `StableNodeId` per signature | `plsql-symbols`, `plsql-depgraph` | See §9.2.2, §10.4 |
| Object types and inheritance | Parsed; semantic IR captures inheritance edges | `plsql-parser`, `plsql-ir` | FINAL/NOT FINAL/INSTANTIABLE flags retained |
| Pipelined functions | Parsed; `plsql-bindgen` emits `Unsupported(Pipelined)` diagnostic with manual-wrapper guidance | `plsql-parser`, `plsql-bindgen` | Automatic stream emission belongs to future bindings-extension plan (BG-X02) |
| Polymorphic table functions | Detected; `UnknownReason::UnsupportedDialectFeature` if grammar doesn't cover | `plsql-parser` | Backlog item |
| Autonomous transactions | Detected via `PRAGMA AUTONOMOUS_TRANSACTION`; flagged in SAST | `plsql-parser`, SAST `QUAL004` | |
| Global temporary tables | Treated as ordinary tables with a session-scope flag | `plsql-catalog` | |
| Materialized view refresh dependencies | Captured in `plsql-catalog`; surfaced in lineage | `plsql-catalog`, `plsql-lineage` | Lineage `Reads`/`Writes` edges show refresh dependencies |
| Triggers with dynamic side effects | Body parsed; dynamic SQL inside trigger surfaces as evidence | `plsql-parser`, `plsql-symbols` | |
| Scheduler jobs calling PL/SQL | Captured in `plsql-catalog` `DBMS_SCHEDULER` metadata | `plsql-catalog` | |
| AQ / `DBMS_SCHEDULER` / `DBMS_JOB` procedural entrypoints | Captured in catalog metadata | `plsql-catalog` | |
| External procedures | Detected; treated as opaque (cannot analyze body) | `plsql-symbols` | `UnknownReason::UnsupportedDialectFeature` |
| Runtime grants / role-mediated authorization | Modeled by `plsql-privileges`; `UnknownReason::RuntimeGrantOrRole` when role-dependent | `plsql-privileges` | |
| Java stored procedures | Detected; treated as opaque (Java body out of scope) | `plsql-symbols` | |
| External tables | Captured in `plsql-catalog`; opaque w.r.t. file contents | `plsql-catalog` | |
| SQL `BOOLEAN` vs PL/SQL `BOOLEAN` | Version-gated via `OracleFeature::SqlBoolean23ai` | `plsql-parser`, `plsql-catalog`, `plsql-bindgen` | SQL BOOLEAN appears in 23ai+; PL/SQL BOOLEAN has older semantics and different client-binding behavior |
| `VECTOR` / `SPARSE VECTOR` / vector arithmetic | Version-gated via `OracleFeature::*Vector*` | `plsql-parser`, `plsql-ir`, `plsql-bindgen` | Needed for 23ai/26ai codebases with AI Vector Search usage |
| Package `RESETTABLE` clause | Version-gated via `OracleFeature::PackageResettable26ai` | `plsql-parser`, `plsql-ir`, `plsql-cicd` | Affects package state and invalidation/reinstantiation semantics |
| JSON-Relational Duality views | Version-gated via `OracleFeature::JsonRelationalDuality23ai` | `plsql-catalog`, `plsql-depgraph` | New object kind in 23ai |
| SQL Macros | Version-gated via `OracleFeature::SqlMacros` | `plsql-parser`, `plsql-symbols` | Affect how SQL text resolves at compile time |

This list is normative: any new Oracle feature found in the corpus that does not appear here must either be added or routed to an `UnknownReason::UnsupportedDialectFeature`. The Hazards table is a release-gate audit point.

---

## 18. Cross-cutting concerns

### 16.1 Repository layout

Per R3: single Cargo workspace. See §6.2.1 for the directory tree.

### 16.2 Versioning

- Workspace-level version in `Cargo.toml`. All crates share the version. (Alternative: independent versions per crate. Decision deferred to D2.)
- Internal `0.x.y` builds may exist only as private validation artifacts (not public releases, not customer rollouts, not product subsets).
- The single public release is GA `1.0.0` when the GA gate (§5) closes. Semver guarantees start there.

### 16.3 CLI conventions

Every CLI shares:

- `--robot-json` flag (R10)
- `doctor` subcommand (R11)
- `--config <file>` for component-specific config
- `--quiet` and `--verbose` flags
- `--log-level <level>` for tracing output
- `--no-color` for CI environments
- Exit codes: 0 = ok, 1 = expected failure (e.g., findings present), 2 = unexpected error, 3 = config error
- `--help` produces miette-rendered help with examples

### 16.4 Configuration files

Workspace-wide root config at **`.plsql-intelligence.toml`** carries the canonical `AnalysisProfile`: Oracle version + compatibility, current schema, current user, current edition, `PLSQL_CCFLAGS`, NLS settings, enabled roles, DB-link policy. Component configs override only component-specific behavior — they no longer carry dialect/schema/edition (that was a v0.2 drift point that v0.3 removes).

Component-specific configs in TOML:

- `.plsql-parser.toml` — parser-specific overrides only (file globs, ignored constructs)
- `.plsql-scan.toml` — rule allowlist/denylist, severity overrides, baseline file path, suppression config
- `.plsql-doc.toml` — output directory, theme, doc-comment style preferences
- `.plsql-bindgen.toml` — target language, type-mapping overrides, date/time backend choice
- `.plsql-lineage.toml` — confidence thresholds, dynamic-SQL strategy, schema scope
- `.plsql-cicd-policy.toml` — invalidation policy gates, predict-mode default
- `.plsql-subset.toml` + `relationships.toml` + `masking-hooks.toml`

### 16.5 Logging and observability

Per R9: `tracing` everywhere. Output to stderr by default; `--log-format json` for structured ingestion. Spans on every public API entry point. Performance-sensitive paths use `trace!` level. No `println!` in library code, ever.

### 16.6 Error handling

Per R8:

- `plsql-core::Diagnostic` is the canonical user-facing error shape (miette-compatible).
- `thiserror::Error` for library-internal `Error` enums.
- `anyhow::Error` only in CLI `main()`.
- No `unwrap()` in library code; `expect()` requires a justification comment.
- Panic policy: parser must never panic on adversarial input (R13's contract). Other components may panic only on programmer errors that indicate a bug.

### 16.7 Performance budgets

| Operation | Budget |
|-----------|--------|
| Parse 10K-line file (cold) | <200ms |
| Build semantic IR for a 100-file schema (cold) | <5s |
| Compute dependency graph for a 100-file schema | <2s |
| `impact(node)` on a 100-file schema | <100ms |
| `what-breaks --change` for a single-DDL change | <500ms |
| Generate docs for a 100-file schema | <30s |
| Generate bindings for a 50-package schema | <10s |

Budgets enforced by `tools/corpus-bench` on every release.

### 16.8 Memory budgets

For a 1000-file schema (representative large customer):

- Parser AST footprint: <500MB
- Semantic IR footprint: <800MB
- Dependency graph footprint: <300MB

Profiled with `dhat` per release.

**Memory strategy** (budgets without architecture are wishes — the plan declares the architecture):

- Intern schema/object/column/member names through `SymbolInterner` (in `plsql-core`)
- Represent cross-model references as compact typed IDs (newtypes), not strings
- Keep the lossless token tape separate from the semantic AST/IR — AST may evict after semantic/fact extraction when `AnalysisRun` is persisted
- Store large source snippets by `Span` reference, not by copying strings
- Use compact graph adjacency structures (CSR or equivalent) for hot lineage queries
- Expose `--memory-profile` flag + `plsql doctor memory` subcommand for runtime introspection
- All compact-ID types implement `Copy` and live behind newtype patterns to prevent ID type confusion

### 16.9 Documentation conventions

- Every public type has rustdoc with at least one example
- Every component has a `docs/components/<name>.md` long-form architecture doc
- Every CLI has a `<name> --help` block with at least 3 invocation examples
- Architecture overview at `docs/architecture.md`
- Decision log at `docs/decisions/` (one file per D-decision once decided)

### 16.10 Provenance and reproducibility

Every output artifact (docs, lineage report, dep graph, generated bindings) carries a header / manifest entry:

```
generated-by: plsql-doc 0.1.0
source-rev: git-sha-of-input or "user-provided-input"
generated-at: ISO-8601 timestamp
input-files: list of file IDs
plan-version: 0.1
```

This allows customers to prove an artifact's provenance during audits.

### 18.11 Redaction and support-bundle policy

Every report-producing component supports a `RedactionPolicy` applied before any output leaves the process:

- `--redaction none` — full source snippets and spans
- `--redaction identifiers` — hash or mask schema / object / column identifiers; keep snippets
- `--redaction snippets` — keep identifiers; remove source snippets
- `--redaction strict` — no source snippets, no literal values, identifiers hashed

Support bundles default to `--redaction strict`. Literal strings from dynamic-SQL evidence are classified as potentially sensitive and redacted unless explicitly allowed. Cache files written by `plsql-store` may carry redacted variants for support-bundle export without re-running analysis.

**Support-bundle hardening:**

- Default to `--redaction strict`
- Optional `--encrypt-to <age|pgp-recipient>` so customers can ship bundles to support without leaving plaintext on shared infrastructure
- Include a **redaction manifest** listing removed fields by category, not by value
- Use a **per-bundle salt** for identifier hashing unless a stable customer salt is configured
- **Literal classifier** runs before export, tagging literals as: credential-like, SQL-like, URL-like, free-text, numeric, date/time, or unknown — credential-like and free-text are scrubbed by default
- Never include raw `plsql-store` cache files — only sanitized derived bundles

This turns "privacy posture" from a risk-table line into an implemented contract. Critical for regulated buyers who want to share diagnostics without leaking source.

#### 18.11.1 Internal support-only repro minimization

**Scope: narrow internal infrastructure. Not a customer-facing product feature, not marketed, not in any SKU.** Used by the founder (and eventually any internal support engineer) to turn an engagement bug or customer-shipped support bundle into a minimal regression fixture for the corpus, without violating C5/C6 or expanding the customer-data attack surface beyond what §18.11 above already permits.

**Why this exists.** With the Commercial Validation Track (§1.6) running, the engine will encounter PL/SQL constructs in real customer estates that don't appear in `corpus/public/` or `corpus/synthetic/`. Each parser panic, false SAST finding, missing dependency edge, or wrong symbol resolution found in a customer estate is a real-world coverage gap. Without a privacy-safe path from "customer bug" to "regression fixture," the founder has three bad options: (a) ask customers to share sensitive source code, (b) debug blind, (c) carry private one-off fixes that never make it back to the public corpus. None of those scale.

**This is NOT:**

- a customer-facing CLI subcommand that customers run on their own code
- a marketed feature ("our tool can minimize your bugs!")
- a SaaS upload endpoint ("upload your failing code and we'll fix it")
- an automated guarantee of zero IP / PII leakage
- a substitute for legal data-handling agreements
- a delta-debugging semantic shrinker (that scope-creep is explicitly out)

**This IS:**

- an offline internal workflow that the founder runs against support bundles already exported by the customer via §18.11 above
- scoped tightly to **parser-recovery-region minimization** in the first implementation: when a customer's support bundle contains a parser panic or a parse-quality regression, find the smallest source fragment that still reproduces the failure
- run on the founder's local machine, against bundles already strict-redacted by the customer
- followed by **mandatory human review** before any minimized fixture lands in `corpus/adversarial/` or `corpus/synthetic/`
- accompanied by a **redaction-delta manifest** documenting every transformation between customer bundle and corpus fixture (identifier rename map, literal classification decisions, structural reductions)

**Workflow:**

1. Customer exports a support bundle using the existing §18.11 `--redaction strict` + literal classifier + per-bundle salt + optional `--encrypt-to` flow. Source already scrubbed at customer's premises.
2. Customer ships the encrypted bundle to the founder via whatever channel their procurement allows.
3. Founder decrypts locally, never on shared infrastructure.
4. Founder runs `plsql support minimize-repro <bundle>` (internal subcommand of the existing `plsql` binary; not advertised in `--help` for end users, available via `plsql support --help`). The subcommand:
   - Replays the failing analysis to confirm the bug still reproduces against the redacted bundle
   - Token-level identifier renaming pass (idempotent with the bundle's existing salt)
   - Literal scrubbing pass (re-runs the §18.11 literal classifier with stricter thresholds)
   - **Parser-level structural minimization** via standard delta-debugging on the redacted source: remove blocks, declarations, statements until the failure stops reproducing
   - Emits a candidate fixture + a redaction-delta manifest
5. **Human review (founder)** of the candidate fixture: read it, confirm no recognizable customer-specific structure remains, decide whether it goes into `corpus/adversarial/` (parser bugs) or `corpus/synthetic/` (new edge-case patterns).
6. If approved: file the fixture with a `corpus/manifest.toml` entry citing the support engagement (engagement ID, not customer name), commit to the public corpus. If rejected: discard everything; the bug stays in the engagement-private notes.

**Hard constraints:**

- The `plsql support minimize-repro` subcommand exists only in the `plsql` binary, behind the `support` subcommand group. Never advertised in customer-facing docs.
- The subcommand refuses to run on input that is NOT already a strict-redacted support bundle (literal-classifier coverage check, identifier-hash signature check, redaction-manifest presence check). No raw PL/SQL input accepted.
- The output never contains anything not already in the input. Minimization is structural reduction only — no synthesis, no fabrication, no LLM-assisted "rewrite this to look generic" steps (C1/C2/C3 prohibit it anyway).
- The redaction-delta manifest is committed *alongside* every corpus fixture that originated from a customer support bundle. Future readers must be able to trace the fixture back to its origin engagement (privacy-safe identifier only) and the transformations applied.
- **No automated path from minimize-repro output to public corpus.** Human review is a hard gate. The subcommand emits a candidate fixture into a staging directory; the founder commits to `corpus/` manually after review.
- **No semantic shrinker.** Repeatedly: this is parser-level structural minimization only. Semantic minimization (changing types, simplifying control flow, rewriting expressions to canonical forms) is scope-creep that introduces correctness risk and is explicitly out of scope for the first release. Add it only if repeated support cases prove it's necessary, and only behind another bead.

**Bead seeds — Internal repro minimization.** Append to §18 cross-cutting beads.

| Bead | Title | Depends | Effort |
|------|-------|---------|--------|
| `PLSQL-SUPPORT-010` | Author `plsql support minimize-repro` subcommand skeleton; refuse non-redacted input | SUPPORT-001 | M |
| `PLSQL-SUPPORT-011` | Implement parser-level delta-debugging shrinker for parser-panic / parse-quality regressions | SUPPORT-010 + WS-008 | L |
| `PLSQL-SUPPORT-012` | Token-level identifier-renaming pass; idempotent with the bundle's per-bundle salt | SUPPORT-011 | M |
| `PLSQL-SUPPORT-013` | Literal scrubbing pass with stricter-than-default thresholds | SUPPORT-012 + SUPPORT-001 | S |
| `PLSQL-SUPPORT-014` | Redaction-delta manifest generator: record every transformation, commit alongside the fixture | SUPPORT-013 | M |
| `PLSQL-SUPPORT-015` | Human-review staging directory + manifest-presence CI check on corpus PRs adding fixtures with `provenance = "support-engagement"` | SUPPORT-014 | M |
| `PLSQL-SUPPORT-016` | Document the support-engagement → minimize-repro → corpus pipeline in `docs/internal/support-corpus-workflow.md` (not customer-facing) | SUPPORT-015 | S |

**Confidence that this scope is right.** This is the version Codex conceded to in its reaction phase: narrow, offline, parser-level only, human-reviewed, never marketed. Gemini's critique of the original broader pitch (academic fantasy, infosec veto, semantic shrinker complexity, 6-month PhD project) was correct — and is addressed here by *not building that thing*. What's left is the modest amount of offline tooling that lets the support workflow improve the public corpus without ever asking customers to expose source they haven't already chosen to expose through the existing §18.11 support-bundle channel.

---

## 19. Test corpus strategy

### 19.1 Three corpora, three roles

| Corpus | Role | Source | Size target |
|--------|------|--------|-------------|
| `corpus/public/` | Real-world parse coverage | Oracle samples, antlr/grammars-v4 tests, public OSS PL/SQL, public APEX source | 500+ files |
| `corpus/synthetic/` | Targeted edge cases + SAST rule positives/negatives | Agent-generated from grammar + pattern descriptions | 1000+ files |
| `corpus/golden/` | End-to-end output snapshots | Generated outputs from running pipeline against fixed inputs | matches synthetic + public |
| `corpus/db-fixtures/` | Live Oracle validation fixtures | SQL install scripts + expected catalog/PLScope/depgraph outputs | 20+ schemas |

### 19.2 Public corpus ingestion

- Oracle HR / OE / SH / PM / IX / BI sample schemas (Oracle publishes these under permissive terms for download — verify per-file license; UPL-1.0 confirmed for most).
- antlr/grammars-v4 PL/SQL test cases (BSD-3).
- Tom Kyte and similar educational examples — **referenced by URL only**, never vendored. Educational content is not redistribution-licensed.
- Public APEX source — only the Apache-2.0 licensed components, per-file license check enforced.
- plsql-utils (public OSS, MIT).
- Trivadis PL/SQL examples that are explicitly published as samples (verify license per file — the Trivadis Cop CLI itself is CC BY-NC-ND 3.0; only the coding-guidelines repository is Apache-2.0).

Public PL/SQL examples from tools with non-commercial / no-derivatives licenses **must not be vendored**. They may be referenced by URL and used only for manual behavioral comparison if license terms permit.

**Per-file license/provenance discipline:** every committed file under `corpus/public/` MUST have an entry in `corpus/manifest.toml` (schema in §6.2.8). The `tools/corpus-license-check/` CI gate fails PRs that add files without manifest entries. Files of uncertain provenance are referenced by URL in the manifest rather than vendored.

### 19.3 Database fixture strategy (`corpus/db-fixtures/`)

Some correctness properties cannot be proven from source files alone. Oracle behavior lives in the database, not only the grammar. `corpus/db-fixtures/` contains installable Oracle schemas for integration tests:

- Overload-resolution fixture
- Synonym-chain fixture (private + public + cross-schema)
- Grants / roles / invoker-rights fixture
- Invalid-object fixture (intentionally broken cascade)
- Conditional-compilation fixture (multiple `PLSQL_CCFLAGS` variants)
- Editioning fixture where supported
- Dynamic SQL fixture (literal, partial, opaque)
- `%TYPE` / `%ROWTYPE` fixture
- PL/Scope fixture (compiled with `PLSCOPE_SETTINGS='IDENTIFIERS:ALL, STATEMENTS:ALL'`)

Each fixture has:

- `install.sql` — DDL to deploy
- `expected-catalog.json` — golden catalog snapshot
- `expected-depgraph.json` — golden dependency graph
- `expected-plscope.json` — golden PL/Scope diff (when applicable)
- `teardown.sql` — clean removal

Fixtures run against an Oracle XE 23ai container in CI where licensing/runtime permits.

### 19.4 Synthetic corpus generation

Per C5 + C6: agents generate test cases from grammar + pattern descriptions. Durak may describe patterns informally (e.g., "a package with a DEFINER-rights private function called from an INVOKER-rights public function, with a row-level trigger on the same table") and the synthetic generator authors a representative test case. The private estate source code is never input to the generator.

The synthetic generator (`tools/corpus-grow/`) is itself agent-friendly:

- Takes a pattern description from `corpus/synthetic/patterns.md`
- Emits one or more files implementing the pattern
- Annotates each generated file with the pattern ID it exercises
- Updates `corpus/synthetic/manifest.json` so test runners can iterate

### 19.5 Golden corpus

For end-to-end tests of each consumer (doc, SAST, lineage, bindgen, etc.), a golden artifact is committed. Updates require `cargo run --bin corpus-update` to re-emit goldens after a deliberate behavior change. CI fails on golden drift.

### 19.6 Adversarial / fuzz corpus

A `corpus/adversarial/` directory holds inputs that historically panicked the parser or caused other failures. Every regression adds an entry. Cargo-fuzz seeds from here.

---

## 20. Distribution & packaging

### 20.1 Distribution channels

| Channel | Audience | Cadence |
|---------|----------|---------|
| crates.io | Rust developers consuming the libraries directly | Per release |
| GitHub Releases | Everyone — prebuilt binaries for Linux x86_64, macOS aarch64, Windows x86_64 | Per release |
| Homebrew tap | macOS users | Per release |
| Docker image (`ghcr.io/<org>/plsql-intelligence`) | CI pipelines | Per release |
| Snap / apt (deferred) | Linux distros | Deferred |

### 20.2 Parser backend packaging

The current release line packages only the in-process Rust parser backend (`plsql-parser-antlr`). The retired Java ANTLR worker is not built, bundled, downloaded on first run, exposed as a CLI option, or kept as an active fallback.

Packaging requirements:

- `plsql doctor` reports the selected parser backend and must not imply a JVM or worker jar is required.
- Release artifacts must remain self-contained for the selected Rust backend.
- Unsupported backend selections fail with an actionable diagnostic, not a panic. Former Java worker backend names are retired and must not be accepted as hidden fallbacks.
- **No ANTLR parse-tree types may cross the `ParseBackend` boundary** — consumers see only our public AST / CST / token tape (R20).

Reintroducing a subprocess backend requires a new decision record and new beads; it is not a hidden configuration switch.

### 20.3 Naming

- Crates: `plsql-core`, `plsql-output`, `plsql-render`, `plsql-store`, `plsql-project`, `plsql-parser`, `plsql-parser-antlr`, `plsql-catalog`, `plsql-engine`, `plsql-ir` (including embedded-SQL semantics, flow state, and `FactStore` emission), `plsql-symbols`, `plsql-privileges`, `plsql-depgraph`, `plsql-doc`, `plsql-sast`, `plsql-bindgen`, `plsql-lineage`, `plsql-cicd`, `plsql-accretion`, `plsql-support`
- Binaries: `plsql` (umbrella CLI with subcommands, including `plsql analyze`) + component binaries that are actually published (`plsql-depgraph`, `usr-loop`, and future standalone component binaries as they earn release gates)
- Marketing name for the family: **TBD** — `plsql-intelligence` is the project key, not necessarily the brand. Brand decision deferred (D15).

### 20.4 Release process

Per the `release-preparations` skill. Tagged versions trigger `release.yml` which:

- Runs full test suite on Linux/macOS/Windows
- Cross-compiles binaries
- Generates SHA256 checksums
- Publishes to crates.io
- Drafts a GitHub Release with notes and assets

---

## 21. Licensing strategy

Per R16: layered.

The entire workspace is dual-licensed **Apache-2.0 OR MIT**. Every
crate — parser, project loader, catalog, semantic IR, symbols,
privileges, flow/facts, dependency graph, engine, lineage, SAST, CI/CD
cascade, doc generator, bindings generator, accretion, and support
tooling — ships under the same permissive license. The project is fully
open source; there is no source-available or commercially-restricted
tier.

**Rationale:** a single permissive license maximizes adoption across
Oracle shops and keeps the whole engine auditable end to end.
Commercial value, where the project pursues it, sits in support,
hosting, and design-partner engagements around the open-source code
(D8, resolved), never in license restriction. The offline pivot leaves
no in-repo MCP license boundary; MCP serving moved to `oraclemcp`
(§13A).

---

## 22. Verification standards

### 22.1 Pre-commit gates (CI)

Every PR must pass:

- `cargo fmt --check`
- `cargo clippy --workspace -- -D warnings`
- `cargo test --workspace`
- `cargo build --workspace --release`
- Parse-quality check: clean parse rate, recovered parse rate, skipped-token ratio, top-level declaration recognition, adversarial no-panic (thresholds in §7.5)
- Golden artifact diff (no drift unless explicitly updated)
- Documentation builds (`cargo doc --workspace --no-deps`)

### 22.2 Release gates

Additionally:

- `cargo audit` clean (no known security vulnerabilities in dependencies)
- `cargo deny` clean (license compliance)
- Cross-platform binary builds succeed on Linux x86_64, macOS aarch64, Windows x86_64
- `tools/release-check/` integration test against an Oracle XE 23ai container
- DB fixture suite (§19.6) passes against Oracle XE 23ai container where licensing/runtime permits

### 22.3 Per-component verification

Each component's acceptance criteria (§7.6, §8.4, §9.5, §10.5, §11.5, §12.5, §13.5, §14.4, §15.5) must pass before merging the component's last bead.

### 22.4 Differential testing

Where possible, run our tool's output against a reference:

- **Parser: black-box differential testing against Oracle Database compilation.** SQL Developer does not expose a stable, automatable, licensed parser API suitable for CI, so the round-trip comparison from earlier drafts is replaced by:
  - deploy fixture units into an isolated Oracle test schema
  - compare parser diagnostics against Oracle compile diagnostics from `USER_ERRORS`
  - compare recognized declarations against dictionary objects
  - compare references against PL/Scope when enabled
  - compare object DDL normalization against `DBMS_METADATA`
  - (SQL Developer parser comparison may be added as a release gate only if a stable, automatable, licensed API is identified and documented in a decision record)
- **Symbol resolution: when a live Oracle database with PL/Scope enabled is available, compare our identifier/reference model against PL/Scope compiler metadata.** Oracle's own compiler is the most authoritative oracle for what PL/SQL identifiers mean.
- **Dependency graph: compare against Oracle's `ALL_DEPENDENCIES` dictionary view as a comparison source (not ground truth — dynamic SQL gives us edges Oracle's metadata doesn't see).**
- Lineage: cross-check against Manta or Atlan outputs where customers grant access (this is a post-launch effort, not a release blocker).
- Bindings: compile and run against Oracle XE 23ai container; verify type round-trip semantics.

---

## 23. Open decisions

### D1 / D2 — Parser implementation strategy `[CLOSED, antlr4rust selected]`

Per R2 + R20, the public architecture remains backend-isolated, but the active implementation route is no longer a tournament. `docs/decisions/D2-backend-final.md` selects the in-process `antlr4rust` backend (`plsql-parser-antlr`) as the production parser path. The former Java ANTLR subprocess spike was retired on 2026-06-28 and removed from the workspace.

Current production eligibility criteria:

- Generated parser builds on Linux x86_64, macOS aarch64, Windows x86_64.
- No panic on adversarial corpus.
- Parse-quality metrics in §7.5 met.
- 10K-line package parse budget met or justified.
- Stable source spans and token identity across runs.
- Memory budget measured against §18.8.

Future parser alternatives require a fresh decision record and bead set. They are not active fallbacks and must not leak backend-internal ANTLR types across the `ParseBackend` boundary.

### D2 — Workspace vs polyrepo `[CLOSED, single workspace]`

Resolved: per R3, single Cargo workspace. Revisit only if release cadences diverge sharply across components.

### D3 — Single binary vs multiple binaries `[OPEN, leaning both]`

Options:

1. **Single `plsql` binary** with subcommands (`plsql parse`, `plsql scan`, `plsql doc`, ...)
2. **Multiple binaries** (`plsql-parse`, `plsql-scan`, `plsql-doc`, ...) installed independently
3. **Both** — provide both shapes; users pick

**Recommendation:** Both. Distributing both is cheap and matches every modern multi-tool CLI (git, cargo, rustup all do this).

### D4 — Dynamic SQL representation in AST `[OPEN, leaning recursive parse]`

See §7.9. **Recommendation:** recursive parse when the SQL is a string literal; emit secondary diagnostics if the inner parse fails; mark as opaque otherwise.

### D5 — Single-file vs project-model parser API `[CLOSED, single-file]`

Resolved: parser is single-file. Cross-file analysis is Layer 2's responsibility.

### D6 — Cross-schema resolution default `[OPEN, leaning enabled]`

See §8.6. **Recommendation:** cross-schema enabled by default; opt-out via config.

### D7 — Bindings generator target language expansion `[FUTURE-PLAN]`

See §12.7. Defer expansion to Go and TypeScript until Rust has paying customers.

### D8 — Project license `[RESOLVED: Apache-2.0 OR MIT]`

**Resolved:** the project ships **fully open source**. The entire
workspace is dual-licensed **Apache-2.0 OR MIT**; there is no
source-available or commercially-restricted tier.

Earlier drafts weighed FSL / BSL source-available models for the
upper-layer crates (lineage, SAST, CI/CD). The resolution is the
fully-permissive option: every crate is OSI-licensed and auditable
from day one, and any commercial value is realized through support,
hosting, and design-partner engagements rather than license
restriction. The later offline pivot removed the in-repo MCP surface
entirely; MCP serving now belongs to `oraclemcp` (see §13A).

### D9 — Masking strategy in subsetter `[OUT-OF-SCOPE FOR THIS PLAN]`

Subsetting itself is routed to a separate future plan (§16). For that future plan: **do not ship a public subsetter that implies safe anonymization through stubs.** Acceptable public-release shapes are:

1. Real masking implementation
2. BYO masking command contract with verification
3. Explicit refusal-by-default for non-anonymized lower-environment extraction

Interface-only code may exist internally, but it must not be marketed or documented as masking. This corrects a contradiction between v0.3 §16 (no stub masking) and v0.3 D9 (ship hook stubs).

### D10 — Licensing of generated bindings code `[CLOSED, customer-owned]`

Generated code is the customer's. Generator binary is dual-licensed per R16.

### D11 — SAST rule pack expansion path `[OPEN, leaning in-house first]`

In-house authoring for the first 50 rules; revisit a customer rule SDK at the 100-rule mark.

### D12 — Column-level lineage in dynamic SQL `[FUTURE-PLAN, leaning Unknown]`

See §13.7. Report column references inside dynamic SQL as `Unknown` unless the value-set is statically inferrable.

### D13 — Liquibase/Flyway interop in CI/CD cascade `[FUTURE-PLAN]`

Native script first; Liquibase interop is a low-marginal-value follow-on.

### D14 — Live workload correlation in lineage `[FUTURE-PLAN]`

Static lineage at first close. AWR/ASH correlation is a separate product layer.

### D15 — Marketing brand name `[OPEN]`

Project key `plsql-intelligence` is internal. Marketing name TBD. **Candidates:** `PLINQ` (PL/SQL Intelligence), `Atlas`, `Mantis`, `Lookout`. **Rejected:** `Codex` (taken by OpenAI), `PLOracle` (sounds Oracle-owned or Oracle-endorsed; invites trademark confusion). Founder decision; not blocking technical work.

### D16 — Oracle connection crate `[OPEN for external live consumers; offline engine has no live default]`

For consumers that need a live Oracle connection (external MCP serving, optional integration tests, and future adapter crates):

1. **Keep the offline engine driver-free by default** — no Oracle socket, credential, or async driver is required for parsing, catalog snapshot ingestion, analysis, SAST, lineage, docs, bindgen planning, CI/CD prediction, or accretion.
2. **Use `oraclemcp` as the live adapter boundary** — MCP/live sessions, guarded writes, and driver capability negotiation belong in the external repository.
3. **Track `oracledb`, `oracle-rs`, and future thin alternatives for external live consumers** — strategic alignment with Rust async-Oracle remains useful, but it must not leak into the default offline feature graph.

**Recommendation:** keep this workspace's default graph offline and stable-channel; do not add new first-party direct driver dependencies outside an explicit adapter boundary owned by `oraclemcp` or a future separately reviewed adapter crate.

**Current signal (2026-05-12).** `cargo info` shows `oracle` at `0.6.3` and `oracle-rs` at `0.1.7`. That is strong enough to treat `oracle-rs` as real and worth tracking, but not strong enough to invert the default-backend recommendation.

**Promotion gate for making `oracle-rs` the default.** Do not switch defaults until `oracle-rs` has all of the following:

- a tagged stable release, not just an active main branch
- Oracle XE 23ai CI coverage on Linux, with macOS/Windows coverage where feasible
- working support for TNS / EZConnect / Wallet basics, LOBs, PL/SQL procedure calls, statement cancellation/timeouts, and the `compile_with_warnings` / `patch_package` flows
- a passing compatibility matrix against the `OracleConnection` trait's required capability set

**Offline-pivot amendment:** the in-repo MCP/live path is retired. After D16/C.6:

- The `OracleConnection` trait remains stable in `plsql-catalog` for adapter consumers and targeted tests, but normal offline analysis uses serialized snapshots or stable row ingestion.
- This repo must not depend directly on the thick `oracle` crate in any release feature graph.
- Distribution docs state that normal engine binaries and Docker images do not bundle or require Instant Client.
- The temporary thick-driver compatibility path is retired; reintroducing one would require a new decision and a new dependency-gate bead.

### D17 — Cache and incremental analysis `[OPEN, foundation-level]`

Per the v0.2 revision: **the foundation data model is now mandatory**, but fine-grained incremental semantic re-analysis remains deferred until performance data proves the exact invalidation strategy.

Foundation level (ship now):

- Content-addressed hashes for source files, token tapes, parse diagnostics, semantic fragments, catalog snapshots, depgraph snapshots
- `plsql-store` crate provides the abstraction
- Stable file/object IDs

Deferred (ship when perf data demands):

- Fine-grained per-fragment invalidation
- Cross-session cache reuse for CI
- Distributed cache (per-customer or per-org)

**Recommendation:** ship hash-based caching from Layer 0 onwards. Even a simple cache changes the feel of the tool and unlocks agent-driven workflows.

### D18 — Dynamic SQL evidence UX `[OPEN]`

Every unresolved dynamic SQL diagnostic must surface its `DynamicSqlEvidence` record in a human-readable form. The customer should see, at minimum:

1. The exact source span of the dynamic SQL construct
2. The expression fragments (literal strings, variable refs, function calls)
3. Whether bind variables were used vs raw concatenation
4. Whether `DBMS_ASSERT` (or equivalent validation) was observed
5. Candidate object names if inferred (with confidence per candidate)
6. The reason static resolution stopped (named via `UnknownReason`)

Open: exact terminal rendering style (miette inline, separate evidence block, JSON-detail link), how much evidence to show in the default report vs the `--verbose` mode, and how to summarize evidence in lineage HTML reports.

### D19 — Public release versioning `[REOPENED v0.8, foundation-first sequencing under commercial-GA-is-1.0]`

The **commercial** product (Change Impact Pro + Release Assurance, §1.4) ships as a single GA at `1.0.0`. Semver guarantees on the paid surfaces start there; there is no public alpha, beta, or partial paid product before commercial GA. That part of the original D19 commitment stands.

What v0.8 changes: the **permissive Foundation OSS tier** (parser, project loader, catalog snapshot, semantic IR, symbols, privileges, sqlsem, flow, facts, depgraph, engine, bindgen, doc generator) MAY ship to crates.io / GitHub Releases on its own cadence as `0.x.y` adoption-tier releases *ahead of* commercial GA, subject to discipline below. This corrects v0.5's overbroad "exactly one public release" framing — which treated the Apache-2.0 lower layers as if they were customer-facing paid product, contradicting their actual purpose (adoption infrastructure that protects the parser's market position against competing parsers).

The foundation-first sequencing is allowed *because* and *only because* it:

- ships permissively licensed code; the entire workspace is Apache-2.0 OR MIT;
- exposes a stable trait/JSON surface that the commercial product will then consume — early adopters who build on Foundation OSS keep working through commercial GA;
- carries the same Trust Block (§1.5) and `UnknownReason` discipline as the GA product — the brand promise applies to the free tier from day one;
- requires the synthetic lab (§6.2.8.1, at least L1) to be public alongside, so the foundation crates ship with a credible eval path;
- preserves the convergence-gate discipline of §5 — foundation crates only publish past their internal quality gates (parser gate for `plsql-parser`, catalog gate for `plsql-catalog`, semantic gate for the L2 trio, graph gate for `plsql-depgraph`).

What is still forbidden under this amendment:

- The upper-layer crates (`plsql-lineage`, `plsql-sast`, `plsql-cicd`) gate public release on their own quality bars (§5), not on licensing — every crate is Apache-2.0 OR MIT.
- There is no separate commercial license. The code is Apache-2.0 OR MIT under R16; commercial customers are Commercial Validation Track design-partner engagements (separate amendment), not a paid license.
- No marketing positioning of foundation releases as a "free tier" of the paid product. They are *adoption infrastructure* — separate framing, separate naming on the docs site, separate roadmap page.
- No release-cadence promises on foundation crates that would force the swarm to prioritize backward compatibility over reaching the commercial-GA gates.

The §5 GA gate language is amended to read: *"GA gate = commercial GA gate. Foundation OSS releases pass per-component convergence gates (parser / catalog / semantic / graph) but do NOT trigger the §5 GA gate."*

### D20 — LSP / IDE integration `[FUTURE-PLAN]`

LSP/IDE integration is a huge adoption channel (Cursor, VS Code, SQL Developer, JetBrains DataGrip). **Do not build before the CLI product proves value.** However, keep schema design compatible with diagnostics, document symbols, go-to-definition, references, hover docs, and call hierarchy.

Specifically:

- `plsql-output` schemas are designed so LSP server implementations can serialize from `AnalysisRun` without reinventing types
- `plsql-engine` `AnalysisRun` is the natural "session" boundary for an LSP
- Doctor subcommands and `explain` commands feed naturally into hover-text and code-actions UX

This keeps the LSP door open without distracting GA work.

---

## 24. Risks

| R# | Risk | Probability | Impact | Mitigation |
|----|------|-------------|--------|------------|
| K1 | `antlr4rust` proves unworkable in practice (panics, perf, runtime missing features) | Medium | High | D2 selected `antlr4rust` with explicit production-eligibility criteria and backend isolation. If it fails those criteria, the mitigation is a new parser decision and bead set, not a retained Java fallback. |
| K2 | Parser coverage stalls below 95% on real-world corpus | Medium | High | Front-load corpus testing; agents continuously author edge-case patterns; weekly corpus-coverage report. |
| K3 | Symbol resolution complexity exceeds estimates (synonyms + DB links + dynamic SQL) | Medium | Medium | Each strategy is independently shippable; ship resolution incrementally with confidence markers. |
| K4 | False-positive rate on SAST rules drives customer churn | Medium | Medium | Per-rule positive + negative corpora; FPR measured as acceptance criterion; baseline mode for incremental adoption. |
| K5 | Bindings generator's `%TYPE` resolution is too imprecise | Medium | Medium | Acceptable to emit `String` + warning for unresolved cases; document manual override patterns. |
| K6 | Oracle's 26ai introduces new PL/SQL constructs that the grammar doesn't cover | Low | Medium | Layer 1 dialect flag (19c / 21c / 23ai / 26ai); contribute grammar updates upstream to antlr/grammars-v4. |
| K7 | IBM (Manta), Atlan, or another incumbent releases a stronger Oracle-PL/SQL-focused offering | Medium | High | Differentiate on offline-first evidence, dynamic-SQL uncertainty reporting (`DynamicSqlEvidence` + flow taint paths), compiler/dictionary cross-checks (PL/Scope diff + `compare-oracle-deps`), reproducible artifacts (`AnalysisRun` with manifest), and Rust-native CLI ergonomics. Avoid competing as a generic catalog UI. The moat is evidence quality, not just speed. |
| K8 | Stian's `oracle-rs` stalls, blocking strategic Rust-async-Oracle story | Medium | Low | D16 keeps `oracle` crate as the primary; `oracle-rs` is upside, not dependency. |
| K9 | Customer-data privacy expectations not met (e.g., a lineage report sent to support contains source snippets) | Medium | High | Shared `RedactionPolicy` (§18.11) applied at the output boundary; strict redaction default for support bundles; literal-value scrubbing in dynamic-SQL evidence; cache encryption option. |
| K10 | Solo founder bandwidth on commercial side (sales, support, marketing) lags engineering | High | Medium | Out of plan scope; bridge via consulting per the strategy session. This project's plan is engineering-only. |
| K11 | Agent swarm produces low-quality code under reduced supervision | Medium | Medium | Strict CI gates (R18 + §20); doctor subcommands as continuous-health checks; each component's acceptance criteria are testable, not subjective. |
| K12 | CI/CD `verify` accidentally modifies a non-disposable Oracle schema because Oracle DDL cannot be rolled back via savepoints | Medium | **Critical** | Require isolated verification target by default; block in-place verification unless `--dangerously-verify-in-place` + interactive schema-name confirmation (§15). Hard guard `PLSQL-CICD-005A`. |
| K13 | Source-only analysis produces misleading results without catalog metadata (`%TYPE` resolution fails silently, overloads collapse, synonyms unresolved) | High | High | `plsql-catalog` is an early dependency (Layer 1.5), not an afterthought. Every degradation produces an explicit `UnknownReason::MissingCatalogObject` record. |
| K14 | SAST false positives damage trust before lineage value is proven | Medium | High | Precision tiers (high-confidence default, medium-confidence marked, house-style opt-in); SARIF `--baseline` mode for incremental adoption; per-rule FPR measured on negative corpus (§12.5). |
| K15 | Render/output god crate causes dependency cycles and slow iteration | Medium | Medium | R5 + the `plsql-output` / `plsql-render` split per §6.2.3-6.2.4. Component-owned domain renderers; shared envelopes only. |
| K16 | Licensing model accidentally permits the commercial use it meant to restrict ("Apache OR commercial" trap) | Medium | High | Resolve D8 before public upper-layer release; never describe upper layers as "Apache OR commercial" without resale protection (§21 D8). |
| K17 | Corpus redistribution issue contaminates the public repository | Medium | Medium | Per-file `corpus/manifest.toml` entries + `tools/corpus-license-check/` CI gate; URL-only references for uncertain-provenance materials. |
| K18 | **Prompt-injection via live-DB result content** — a malicious row value, CLOB / LOB blob, comment, or stored procedure error message poisons an external MCP response and steers the agent. Specific to live-DB tools owned by `oraclemcp`, not the offline engine | Medium | Medium | Keep offline engine outputs structured through the `plsql-output` envelope and preserve `UnknownReason` provenance. `oraclemcp` owns live-result sanitization, MCP protocol delimiter handling, and live-DB security docs. |
| K19 | **Accidental writes to a production Oracle database** despite read-only-by-default. Specific to external live-DB tools owned by `oraclemcp` | Medium | **Critical** | This repo must not implement live write tools. `oraclemcp` owns read-only-by-default, operator confirmation, preview/execute approval tokens, permanently read-only connection flags, schema-name confirmation, and live audit markers. |

---

## 25. Bead transfer plan

This plan is structured for mechanical conversion to `br` beads via the `beads-workflow` skill.

### 25.1 Mapping

- One **layer** = one bead label group (`layer:0`, `layer:1`, `layer:2`, `layer:3`, `layer:4`, `layer:5`)
- One **component** = one parent bead with `component:<name>` label
- One **bead seed** in in-scope sections = one bead. Explicit future-plan placeholders in §13.6 (Bindings future-extension notes) and §16 (subsetter) are **not** converted.
- Bead dependencies in `br` match the `Depends` column in seed tables
- Effort tags (S/M/L/XL) map to bead labels
- Every bead inherits `project:plsql-intelligence`

### 25.2 Cross-cutting beads

In addition to component beads, the following cross-cutting beads will be created:

- `PLSQL-DOC-INDEX-001` — Top-level architecture doc at `docs/architecture.md`
- `PLSQL-DOC-INDEX-002` — Per-component design docs at `docs/components/*.md`
- `PLSQL-RELEASE-001` — **First public release of the full GA product** (1.0.0): parser + project + catalog (with PL/Scope + capability negotiation) + engine + IR + symbols + privileges + sqlsem + flow + facts + depgraph + docs + SAST + bindings + lineage + CI/CD cascade. All in-scope components must converge. This bead closes when every other bead in this plan is closed. (Customer-pilot tracking is out of scope of this plan; it belongs to ops/sales workflow, not the engineering plan.)
- `PLSQL-CORPUS-CONTRIB-001` — Ongoing corpus contribution as agents discover edge cases (continuous bead, re-opened each release)
- `PLSQL-DECISION-LOG-001` — Convert each `[OPEN]` decision into a tracked bead once decided

### 25.3 Bead-creation strategy

Use the `beads-workflow` skill to convert this plan to beads in one pass. After conversion:

- Each layer's beads are linked with `blocks` relationships matching dependency arrows in §5
- Acceptance criteria copied verbatim from each component section
- Labels: `project:plsql-intelligence`, `layer:N`, `component:<name>`, effort tag

---

## 26. Glossary

| Term | Meaning |
|------|---------|
| **AST** | Abstract Syntax Tree — output of the parser; reflects source structure faithfully. |
| **Bead** | A unit of trackable work in `br` (beads_rust). Always has acceptance criteria. |
| **Cascade** (recompilation) | The set of Oracle objects that invalidate when a dependency is altered. |
| **Confidence** | A scalar in [0.0, 1.0] indicating how certain a dependency edge or lineage path is. |
| **Dynamic SQL** | SQL constructed at runtime from strings (`EXECUTE IMMEDIATE`, `DBMS_SQL`). |
| **Edge kind** | Typed category of a dependency edge (Calls, Reads, Writes, ...). |
| **FSL** | Functional Source License — source-available with non-compete, converts to OSI after delay. |
| **Golden artifact** | A committed expected output for an end-to-end test; drift fails CI. |
| **IR** | Intermediate Representation — typed, canonical form of code between AST and analysis. |
| **Lineage** | Cross-object impact analysis: what reads/writes/calls what. |
| **Miette** | Rust crate for diagnostic-quality error rendering with source spans. |
| **Opaque** | A dependency edge that cannot be statically resolved; carries confidence 0.0. |
| **Provenance** | Metadata explaining where a piece of derived data came from. |
| **REF cursor** | Oracle PL/SQL construct: a reference to an open cursor passed between procedures. |
| **SARIF** | Static Analysis Results Interchange Format — JSON schema for SAST findings. |
| **Soft reference** | A logical reference between tables not enforced by a foreign key. |
| **Subsetting** | Extracting a referentially-consistent subset of a database. |
| **Symbol resolution** | The process of mapping a name in source to the declaration it refers to. |
| **Synonym** | An Oracle alias for a schema object, potentially in another schema. |

---

## 27. Reference assets

| Asset | Location | Purpose |
|-------|----------|---------|
| Initial ideas doc | `/home/md/carriercall/workspace/initial-ideas.md` | Strategic context, the 12 gaps, the speed ranking |
| antlr/grammars-v4 PL/SQL | https://github.com/antlr/grammars-v4/tree/master/sql/plsql | Starting grammar (BSD-3) |
| antlr4rust runtime | https://github.com/antlr4rust/antlr4 | Rust runtime for ANTLR |
| Trivadis PL/SQL Cop CLI | https://github.com/Trivadis/plsql-cop-cli | Behavioral inspiration only; **license is CC BY-NC-ND 3.0** — do NOT copy code or test assets |
| Trivadis PL/SQL & SQL Coding Guidelines | https://github.com/Trivadis/plsql-and-sql-coding-guidelines | Rule inspiration; guidelines repository is Apache-2.0 |
| Z PL/SQL Analyzer (ZPA) | https://github.com/felipebz/zpa | SonarQube plugin; PL/SQL static-analysis reference. **LGPL-3.0** — useful for behavioral comparison, avoid code copying into permissive crates without legal review |
| Oracle PL/SQL Language Reference 19c | https://docs.oracle.com/en/database/oracle/oracle-database/19/lnpls/ | Authoritative grammar reference |
| Oracle PL/SQL Language Reference 23ai | https://docs.oracle.com/en/database/oracle/oracle-database/23/lnpls/ | Newer features |
| Oracle SQL Language Reference | https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/ | SQL grammar reference |
| Oracle sample schemas | https://github.com/oracle-samples/db-sample-schemas | HR, OE, SH, PM, IX, BI |
| SARIF 2.1.0 schema | https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html | SAST output format |
| miette | https://github.com/zkat/miette | Error rendering |
| thiserror | https://github.com/dtolnay/thiserror | Library error derivation |
| tracing | https://github.com/tokio-rs/tracing | Structured logging |
| oraclemcp | https://github.com/MuhDur/oraclemcp | External MCP server and live Oracle session host that may consume this engine's library contracts |
| oracle-rs | https://github.com/stiang/oracle-rs | Async pure-Rust Oracle access |
| Liquibase FSL announcement (precedent) | https://www.businesswire.com/news/home/20251118678009/ | Licensing model reference |

---

## 28. Status log

- **2026-05-12 (round 10, catalog live-loader API correction)** — **v0.12 DRAFT** — Corrected a real contract bug created by the earlier `CatalogSnapshot` serialization fix. Once the snapshot began persisting its `SymbolInterner`, it became clear that the existing public live-loader signature `load_snapshot_from_connection(conn, schemas: &[SchemaName])` was not actually safe or self-describing outside the originating interner context: raw `SchemaName` wrappers only carry numeric symbol IDs, not Oracle schema-name text. Changes:
  - **Front-matter Status line** refreshed to v0.12 summary.
  - **§8.2.1 `plsql-catalog` public API** now replaces the `schemas: &[SchemaName]` parameter with `CatalogLoadRequest { schema_filters: Vec<CatalogSchemaFilter> }`.
  - **`CatalogSchemaFilter`** introduced in the plan with `CurrentSchema` and `Named(String)` variants so schema selection is text-backed and safe to pass across CLI, JSON, tests, and future MCP surfaces without hidden interner coupling.
  - **Layer 1.5 bead table** updated to add `PLSQL-CAT-019` as the discovered design-correction bead, and `PLSQL-CAT-004` now explicitly depends on it.
- **2026-05-12 (round 9, market revalidation + SQLcl correction)** — **v0.11 DRAFT** — Re-validated the public market and MCP claims against current Oracle, Atlan, Collibra, Alation, SonarQube, Veracode, and Liquibase docs. Oracle SQLcl MCP now has 6 documented tools, restrict-level controls, audit logging, and 26.1 `schema-information` enhancements, so the older "fixed 5-tool ceiling" framing was no longer precise. Repositioned `plsql-mcp` from "replace SQLcl wholesale because it is frozen" to "interoperate with SQLcl's connection store and exceed its current generic surface on PL/SQL-centric semantics and controlled patch/deploy flows." Competitive language was tightened so the documented gap is now stated as package-aware offline semantics + uncertainty accounting + recompile planning, not the absence of any Oracle lineage/SAST products. Added named live-DB safety profiles and tightened D16 with explicit `oracle-rs` promotion gates. Changes:
  - **Front-matter Status line** refreshed to v0.11 summary.
  - **§1.2 Why this project, why now** rewritten to reflect current public docs: Atlan Oracle lineage is AWR/query-history centered, Collibra documents Oracle SQL lineage plus JDBC harvesting limits, Alation's published stored-procedure-lineage connector list omits Oracle, SonarQube and Veracode are acknowledged as real PL/SQL SAST players, SQLcl MCP demand is now treated as category validation rather than a static competitor snapshot, and Liquibase Secure wording is updated from "pivot" language to current AI-governance framing.
  - **§1.4 / §1.5 positioning language** tightened so the moat is framed as offline package semantics + explicit uncertainty accounting + recompile planning, not overbroad claims about competitors having no Oracle support.
  - **§13A.1 Purpose** corrected: SQLcl MCP is now described as a 6-tool, actively-evolving Oracle surface; `plsql-mcp` is positioned as the PL/SQL-centric complement/exceeding surface rather than a "SQLcl but Rust" clone.
  - **§13A.3 Architecture** strengthened with first-class `~/.dbtools` reuse and named safety profiles (`static_only`, `inspect_only`, `ddl_guarded`, `session_write_enabled`) reported by `doctor` / `current_database`.
  - **§13A.5 Acceptance criteria** now require `~/.dbtools` interoperability, active-safety-profile reporting, and a dated SQLcl compatibility matrix before release.
  - **§13A.6 Bead seeds** updated in place: `PLSQL-MCP-LIVE-002` now explicitly owns `~/.dbtools` interoperability, `PLSQL-MCP-LIVE-008` now owns named safety profiles in addition to read-only-by-default gating, and new `PLSQL-MCP-LIVE-021` owns the dated SQLcl compatibility matrix.
  - **D16** now has an explicit promotion gate for any future `oracle-rs` default-backend switch: stable tag, XE-backed CI, capability parity, and live-DB workflow coverage. Recorded current crate signal from `cargo info`: `oracle` `0.6.3`, `oracle-rs` `0.1.7`.
- **2026-05-11 (round 8, live-DB connectivity absorbed into plsql-mcp)** — **v0.10 DRAFT** — Operator-driven amendment after market verification concluded that the then-current Oracle SQLcl MCP surface was still too small and generic for the autonomous-agent workflow (package-aware compile-with-warnings, targeted patching, structured describe, lock-free deploy, dependency analysis). Decision: absorb basic live-Oracle-connectivity tools into the free `plsql-mcp` (Apache-2.0) alongside the existing static-analysis surface, behind a `live-db` Cargo feature flag. Re-clarifies the Track B boundary in §2.2 — what stays out-of-scope is production-operations-fleet features (SIEM forwarding, OpenTelemetry distributed tracing, multi-tenant credential broker, FedRAMP / HIPAA retention, OCI IAM SSO federation, fleet quota management, compliance reporting); developer-grade live-DB is now in-scope. Strengthens free-tier value (designed to exceed the generic SQLcl MCP developer workflow; ~30-tool surface vs SQLcl's then-current small surface; Apache vs closed; plugin-extensible) without weakening the paid-tier upsell (deep semantic tools — what-breaks, change classification, recompile plan, SARIF, release gate, orphan candidates — stay in `plsql-mcp-pro` FSL and are unreachable via SQLcl-MCP-replicable raw-SQL alone). Twenty new bead seeds `PLSQL-MCP-LIVE-001..020`. Two new risks (K18 prompt-injection-via-live-DB-result-content, K19 accidental-writes-to-production) with mitigation patterns ported from the workspace's existing `oracle-mcp/server.py` safety design. Changes:
  - **§13A.1 Purpose** expanded — two-binary table now reflects both static-analysis + live-DB tool families in `plsql-mcp`; commercial-tier inheritance chain made explicit (`plsql-mcp-pro` inherits all foundation + live-DB tools, adds commercial semantic tools); duel-resolution language amended to note that v0.10 also closes the SQLcl-MCP capability gap.
  - **§13A.2 Tool surface** — new third sub-table "Live-DB connectivity tools" added between Foundation and Commercial: ~22 tools across connection management, query, live schema browsing, live source access, compile, patch & deploy, write posture. Each tool annotated with one of four safety classes: read-only / requires write enablement / per-operation approval / operator-explicit. Hard guards enumerated: `permanently_read_only` flag, interactive schema-name confirmation, statement-marker audit, `V$SESSION.MODULE`+`V$SESSION.ACTION` tagging.
  - **§13A.3 Architecture** — removed "No live database queries" anti-scope paragraph (v0.9 framing inverted by v0.10). Added seven new subsections: live-DB connectivity Cargo feature, connection management via `OracleConnection`, credential storage policy (no plsql-mcp-specific store; reuses TNS / wallet / dbtools / OCI IAM), audit baseline (matches SQLcl MCP convention), read-only-by-default safety guard, per-operation approval flow with single-use 60s-TTL byte-exact tokens, `permanently_read_only` hard guard, driver dependency (`oracle` crate today, `oracle-rs` opt-in via D16/MCP-D5, Instant Client install never bundled per §19 Apache constraint). Restated boundary with the *narrowed* Track B (production-ops-fleet features only).
  - **§13A.5 Acceptance criteria** — partitioned into Static-analysis / Live-DB / Cross-surface sections. Live-DB criteria: tools work against Oracle XE 23ai container, `live-db` feature off-state retains static tools, doctor reports Instant Client + OracleConnection, `enable_writes` flow refusals tested, `permanently_read_only` block tested, `V$SESSION` markers verified, `preview_sql` → `execute_approved` token flow rejects expired / mismatched / modified-DDL tokens, K18 sanitization test scrubs synthesized injection markers, cross-schema confirmation requires exact schema-name match, hero demo runs end-to-end via live-DB chained with `plsql-mcp-pro` static tools, MCP `_meta.session.client_info` propagated into `V$SESSION.ACTION`.
  - **§13A.6 Bead seeds** — new middle table "Layer-3 live-DB foundation work" between foundation-static and Layer-5-commercial. 20 beads `PLSQL-MCP-LIVE-001..020`: feature flag + doctor, connection management, audit baseline, query with K18 sanitization, list_objects, describe_*, source/CLOB/errors, read-only-default + enable_writes, permanently_read_only, compile_with_warnings, preview_sql + read_patch_preview, patch_package, patch_view, create_or_replace, execute_approved + deploy_ddl, interactive cross-schema confirmation, doctor extensions, Oracle XE integration test, hero demo via live-DB, per-platform integration walkthroughs.
  - **§13A.7 Open questions** — added MCP-D5: live-DB driver backend, recommending the same `oracle` → `oracle-rs` trajectory as D16, noting v0.10 makes `plsql-mcp` the highest-volume `OracleConnection` consumer and may accelerate D16 closure.
  - **§2.1 In Scope table** — `plsql-mcp` row description rewritten to enumerate both tool families (static + live-DB) with safety-flow summary; `plsql-mcp-pro` row clarified to inherit foundation + live-DB tools and add commercial semantic surface.
  - **§2.2 Out of Scope** — "Live-DB Oracle MCP server" line replaced with "Production-operations Oracle MCP server" reflecting the boundary shift; basic developer-grade live-DB moved IN, fleet-ops surface stays OUT. Explicit list of what's still out: SIEM forwarding, OpenTelemetry distributed tracing, multi-tenant credential broker, FedRAMP / HIPAA retention configuration, OCI IAM SSO federation, per-tenant rate limiting, fleet-visibility dashboard, compliance reporting.
  - **§1.4 SKU framing** — Foundation OSS row contents expanded to reflect `plsql-mcp` now ships with live-DB tools.
  - **§6.2.1 workspace tree** — `plsql-mcp` crate annotation updated to note `live-db` Cargo feature, default-on-for-binary / optional-for-library, and Instant Client runtime requirement.
  - **D16 amendment** — added v0.10 paragraph: `plsql-mcp` (live-db feature) is the primary `OracleConnection` consumer; `OracleConnection` trait must be stable in `plsql-catalog` from v0.10 onward; Instant Client never bundled (preserves Apache-2.0 redistribution); per-platform install docs at MCP-LIVE-020.
  - **K18 + K19 added to §22 risks table** — K18 covers prompt-injection-via-live-DB-result-content with sanitization through `plsql-output` envelope + JSON-schema structuring + `UnknownReason::ResponseSanitized` provenance note; K19 covers accidental writes to production with the read-only-by-default + `enable_writes` token + `preview_sql`/`execute_approved` flow + `permanently_read_only` hard guard pattern. Mitigations ported from a proven production Oracle MCP server that has run this safety design.
  - **Front-matter Status line** refreshed to v0.10 summary.
- **2026-05-11 (round 7, post-duel follow-up amendments)** — **v0.9 DRAFT** — Three contested / killed-but-salvageable ideas from the dueling-wizards synthesis re-evaluated and landed after operator approval. Engineering architecture still unchanged; this round adds one product surface (MCP), one operational program (Commercial Validation Track), and one narrowly-scoped internal support workflow (repro minimization). Two other duel follow-ups (ApplicationEndpoint placeholder, market-fork experiments) were explicitly rejected by the operator and remain unlanded. Changes:
  - **§1.6 Commercial Validation Track** added — productized $25k–$40k fixed-fee design-partner Impact Assessment program. Hard operational guardrails committed in writing: max 2 concurrent / max 6 total engagements pre-commercial-GA, warm-intro-only, on-prem tooling only, written no-custom-feature clause, standard report template never bespoke, every manual step becomes a public bead or an explicit reject. ICP qualifier (200+ PL/SQL objects, frequent releases, manual-impact-analysis pain, governance gap, on-prem compatibility, warm-intro decision-maker). Mitigates K7 / K10 / K13 / K14 / K17. The report deliverable is generated by the same `AnalysisRun` machinery that drives commercial-GA, with sections: Trust Block, dependency + lineage inventory, `compare-oracle-deps`, dynamic-SQL uncertainty, risky-change scenarios, spec/body invalidation summary, orphan candidates with AUDIT statements, SAST appendix, remediation pathway. 10 new operational bead seeds `PLSQL-CVT-001..010` under `area:commercial` label.
  - **§13A Layer 3+ MCP Adapter Surface** added — resolves the duel's most strategically interesting unresolved fork (Gemini's MCP-as-primary-wedge vs Codex's MCP-as-future-adapter) by splitting into two binaries with two licenses: free `plsql-mcp` (Apache-2.0 OR MIT, foundation-tier semantic tools only — parse, symbols, depgraph, dynamic-SQL evidence, completeness, compile-check, doc lookup, profile inspect) for viral developer adoption in Cursor / Claude Desktop / Devin / Windsurf; paid `plsql-mcp-pro` (FSL per D8, license-gated commercial tools — what-breaks, classify-change, compare-oracle-deps, sarif-scan, release-gate, recompile-plan, orphan-candidates, explain-lifecycle) shipping bundled with Change Impact Pro + Release Assurance SKUs. Two binaries (not one runtime-toggled binary) keep the license boundary clean; pro fallback to foundation tools on missing license avoids hard-error trial UX. Trust Block (§1.5) carried in every MCP response as `meta.trust_block`. stdio default + optional TCP transport; no live DB sessions (preserves separation from the still-out-of-scope live-DB Oracle MCP, §2.2). Naming: `plsql-mcp` in code / `plsql` as MCP server identity / *"Oracle PL/SQL MCP server"* in marketing copy — never `oracle-mcp` (D15 trademark-confusion rejection applies). 20 new bead seeds: foundation `PLSQL-MCP-001..012` (Layer 3, depends on engine completion), commercial `PLSQL-MCP-PRO-001..008` (Layer 5, depends on lineage + CICD). Four open `MCP-D1..D4` decisions (license-key format leans offline public-key-signed, MCP library choice deferred to spike, lab-resources opt-in, per-tool cost estimates included from day one).
  - **§18.11.1 Internal support-only repro minimization** added — reframes Codex's idea #4 (originally pitched as customer-facing `plsql minimize-repro` with semantic shrinker, scored 450/1000 by Gemini as academic fantasy / infosec veto / 6-month PhD project) into Codex's reveal-phase concession: **narrow internal offline workflow, parser-level structural minimization only, mandatory human review, never customer-facing, never marketed, no SaaS upload, no LLM-assisted rewriting**. Bridges the Commercial Validation Track (§1.6) to the public corpus: a parser panic discovered in an engagement becomes a regression fixture in `corpus/adversarial/` via the existing §18.11 strict-redacted support-bundle channel + token-level identifier renaming + delta-debugging structural reduction + redaction-delta manifest + founder human review. Hard constraints: refuses non-redacted input, output ⊆ input (no synthesis), no semantic shrinker, no automated path to corpus (human review is a hard gate). 7 new bead seeds `PLSQL-SUPPORT-010..016`.
  - **§2.1 In Scope table** updated — added MCP Adapter Foundation (`plsql-mcp`, Layer 3) and MCP Adapter Pro (`plsql-mcp-pro`, Layer 5) component rows.
  - **§2.2 Out of Scope** clarified — "Oracle MCP Server (Rust)" line refactored to "Live-DB Oracle MCP server" with explicit distinction from in-scope engine-MCP (`plsql-mcp` / `plsql-mcp-pro` are static-source-analysis only, no live DB sessions / SIEM / credential broker — wider Track B scope remains a separate project).
  - **§1.4 SKU framing** amended — `plsql-mcp` listed under Foundation OSS tier; `plsql-mcp-pro` commercial tools split across Change Impact Pro and Release Assurance SKUs.
  - **§6.2.1 workspace tree** updated — added `plsql-mcp/` and `plsql-mcp-pro/` crate entries with layer annotations.
  - **§19 license stack** updated — `plsql-mcp` Apache-2.0 OR MIT row; `plsql-mcp-pro` FSL row per D8.
  - **Two duel follow-ups deliberately not landed** per operator instruction (2026-05-11 session): `ApplicationEndpoint` / `ExternalUsage` placeholder node model in `plsql-depgraph` (would have reserved Phase-2 ingest hooks for APEX / Java callers / scheduler jobs) and pre-amendment market-fork experiments (would have posted `plsql-mcp` to r/oracle + HN and cold-outreached 5 release-engineering leads before further commercial restructuring). These remain open ideas in `DUELING_WIZARDS_REPORT.md` but are not committed plan content.
- **2026-05-11 (round 6, dueling-wizards synthesis)** — **v0.8 DRAFT** — Six consensus winners from a Codex (gpt-5.5 xhigh) vs Gemini 3 Pro adversarial duel landed as plan amendments. The duel covered 30→5 independent ideation, 0–1000 cross-model scoring, reveal-phase reactions, and a synthesis report at `DUELING_WIZARDS_REPORT.md`. Six ideas scored ≥700 by *both* models (with self-confessed opposite biases: Codex = systems-architect / conservative-DBA; Gemini = venture-backed-CEO / product-marketer). Operator approved all six. Amendments are commercial-design changes — no architectural rework. Engineering plan (layers, dependency graph, R-rules, founder constraints, license stack) unchanged.
  - **§1.4 Commercial Nucleus** added — declares *"Oracle Change Impact + Recompile Assurance"* as the single paid buying story. Three-SKU framing (Foundation OSS / Change Impact Pro / Release Assurance) with explicit demotion of SAST → audit appendix, docs → adoption surface, bindgen → developer-love wedge. Hero demo (DROP COLUMN scenario) named as the canonical product proof. Anti-positioning guard against Liquibase/Manta/Atlan comparisons made standing policy.
  - **§1.5 Evidence UX Release Gate** added — promotes the existing CompletenessReport / UnknownReason / DynamicSqlEvidence / Confidence / provenance machinery from internal correctness mechanism to the central product UX and brand promise. Mandatory Trust Block (specific counts, no fake scalar) on every customer-visible report. Hard requirements wired into §22 release gates and §5 GA gate. Explicit rule: every Unknown must be actionable (paired with a remediation hint), not apologetic.
  - **§6.2.8.1 `corpus/lab/`** added — public synthetic Oracle estate (telecom-billing-flavored, no private estate patterns under C5/C6) doubling as sales demo + self-serve evaluation + AI-swarm regression target + golden test suite + docs source. Three-layer build plan (L1 seed 10 packages → L2 working 30 packages → L3 realistic 75+ packages with DB-link / wrapped / missing-body / $IF / autonomous-tx / edition-based / opaque-dynamic-SQL hazards). `make demo-no-db`, `make demo-oracle-xe`, `make demo-all-personas`, `make demo-record`. Lab acceptance criteria part of §22 release gate. 10 new bead seeds `PLSQL-LAB-001..010`.
  - **D19 reopened** — *commercial* GA-is-1.0 commitment stands for the paid tiers, but the permissive Foundation OSS tier MAY ship as `0.x.y` adoption-tier releases ahead of commercial GA, subject to convergence-gate discipline. Explicit guards: no public release of `plsql-scan` / `plsql-lineage` / `plsql-cicd` / `plsql-subset` before commercial GA; no paid SKU before commercial GA; foundation releases positioned as "adoption infrastructure," not "free tier." Synthetic lab L1 must be public alongside foundation releases.
  - **§14.7 PR Integration** added (under CI/CD cascade) — `plsql gate --pr-comment-json` + reference CI templates (GitHub Actions / GitLab CI / Bitbucket / Jenkins) + `plsql post-pr-comment` self-hosted poster subcommand. Hosted GitHub App / multi-tenant SaaS explicitly out of scope (violates R17 trust posture). Idempotent comment update logic, Trust Block in collapsed one-liner header, structured sections for blast radius / release-gate verdict / SAST findings / recompile plan / improve-confidence remediation. 9 new bead seeds `PLSQL-CICD-014..022`.
  - **§13.8 Orphan Candidates Report** added (under Lineage) — productized cleanup / security-posture / Oracle-license-cost-reduction report. Mandatory three-tier confidence partitioning (High / Medium / Low) with explicit 30/60/90-day AUDIT-based observation windows. Hard guard: no "drop tomorrow" language; no deletion scripts; the report emits AUDIT-enablement statements, never DROP statements. Tier classifier consumes `CompletenessReport` + grants + synonyms + scheduler + DB-link signals. 6 new bead seeds `PLSQL-LIN-018..023`.
  - **§13.9 + §14.8 open-question subsections renumbered** from §13.7 / §14.6 to accommodate new §13.8 / §14.7 sections.
  - **Follow-up amendments documented in `DUELING_WIZARDS_REPORT.md`, NOT yet landed in plan** (await separate operator approval): (a) "Commercial Validation Track" — productized $25k–$40k design-partner Impact Assessment program pre-commercial-GA, scoped warm-intro-only with operational discipline; (b) reserve `ApplicationEndpoint` / `ExternalUsage` node placeholder in `plsql-depgraph` to enable Phase-2 APEX / Java-caller / scheduler-job ingestion without graph redesign; (c) reframe §18.11 redacted-repro pipeline as narrow internal offline support infrastructure, not a customer-facing feature; (d) split MCP server into free `plsql-mcp` (Apache, foundation-tier tools only) + paid `plsql-mcp-pro` (FSL, lineage/SAST/CI tools license-gated) — resolves Track B vs Track A tension and gives the Foundation-OSS-as-adoption-funnel story a concrete dev-tool surface; (e) two pre-amendment market experiments (post minimal MCP to r/oracle + HN, cold-outreach 5 release-engineering leads with assessment one-pager) to validate the AI-developer-tool-wedge vs change-governance-wedge fork before any further commercial restructuring.
- **2026-05-11 (round 5)** — **v0.7 DRAFT** — Fifth refinement round integrated. Steady-state cleanup only. Changes:
  - **Out-of-scope work items defanged from bead conversion**: `PLSQL-BG-X01` / `PLSQL-BG-X02` converted from bead-ID rows to a prose "future bindings-extension placeholders" block; subsetter §16.6 retitled "Future subsetter work items — NOT converted in this plan" with a `beads-workflow`-must-not-convert warning; `PLSQL-RELEASE-002` removed (customer-pilot tracking is ops/sales, not the engineering plan); §23.1 mapping now explicitly excludes future-plan placeholders from conversion.
  - **D9 vs §16.7 contradiction closed**: §16.7 D9 entry replaced with the `[OUT-OF-SCOPE]` framing matching D9's main entry.
  - **Bead-graph layer hygiene** — beads relocated to honor their actual dependencies:
    - Layer 0: `PLSQL-CORE-IDS-001`, `PLSQL-SUPPORT-001`, `PLSQL-SUPPORT-002` (previously in Layer 1 table)
    - Layer 2 §9.5: `PLSQL-SUPPORT-003` (depends on FLOW-001), `PLSQL-PLSCOPE-DIFF-001` + `PLSQL-PLSCOPE-DIFF-002` (renamed from `PLSQL-CAT-012`/`013`; they depend on `SYM-003` which is Layer 2)
    - Layer 2.5 §10A.3: `PLSQL-PERF-001`, `PLSQL-PERF-002`, `PLSQL-STORE-DAEMON-001`, `PLSQL-STORE-DAEMON-002` (all depend on ENG-* or FACT-005)
  - **Corpus layout** §6.2.1 now includes `corpus/db-fixtures/` (referenced by R6 + §19.6 but missing from the workspace tree); §6.2.8 enumeration expanded from three sub-directories to five with explicit `adversarial/` + `db-fixtures/` rows.
  - **Residual wedge / stale wording purged**: §6.2.5 "first-product-surface CLIs" → "product-surface CLIs"; §7.2 "Deferred (Layer 1.5 or later)" → "Out of current GA scope / future-plan items"; §7.2 "revisit Q4 2026" → "routed through `UnsupportedDialectFeature`"; §12.1 "First close ships" → "GA ships"; §13.1 "First close: Rust target only" → "GA scope: Rust target only"; §18.2 versioning text aligned with D19 (single public release is GA 1.0.0).
  - **`plsql-privileges` acceptance criteria** tightened from one line to five concrete gates covering definer/invoker classification across declaration kinds, grant/role/PUBLIC/synonym/`ACCESSIBLE BY` fact emission, role-mediated runtime unknowns, SEC004 evidence integration, and privilege doctor coverage report.
  - **`plsql-flow` + `plsql-facts` acceptance criteria** made falsifiable: ≥10 fixtures per fact family, golden JSON snapshots, fact-ID stability across whitespace-only changes, one integration test per product surface proving FactStore-only consumption is sufficient for its inventory queries.
  - **SAST harness** depends on `FactStore` / `AnalysisRun` instead of raw semantic model: `PLSQL-SAST-001` adds `RuleSkippedDiagnostic` type and depends on `FACT-001 + FLOW-005`; `PLSQL-SAST-002` loads from engine artifact and honors `required_facts` + `minimum_completeness` before firing.
  - **PLAN-003 target scheme** specified: every subsection number inherits its parent section number (`§11.1`, `§12.1`, `§10A.1`, etc.); no legacy numbers from earlier section positions remain.
  - **D15 candidates pruned**: rejected `PLOracle` (sounds Oracle-owned or Oracle-endorsed; trademark-confusion risk); kept `PLINQ`, `Atlas`, `Mantis`, `Lookout`; `Codex` rejection retained (taken by OpenAI).
- **2026-05-11 (round 4)** — **v0.6 DRAFT** — Fourth refinement round integrated. Consistency cleanup approaching steady-state. Changes:
  - **§2.1 engine row** corrected: Layer 0 → Layer 2.5 (residue from v0.5 architectural fix)
  - **§5 diagram split**: Layer 3 product surfaces (scan, doc, bindgen) / Layer 4 (lineage) / Layer 5 (cicd). Earlier diagram had lineage under Layer 3 contradicting §14.
  - **New §10A Layer 2.5 section** with engine purpose, acceptance criteria, and ENG-001..005 bead seeds. Earlier §6 had ENG beads but no Layer 2.5 component section.
  - **ENG-001..004 removed from Layer 0 seeds**, leaving only ENG-000 (skeleton). Implementation now lives in §10A.3 where its Layer 2 dependencies are honored.
  - **Two real dependency cycles fixed**:
    - SQLSEM-004 → DEP-003 (Layer 2 SQL semantics cannot depend on Layer 2 dependency graph). Rerouted: SQLSEM-004 emits facts; DEP-004 consumes SQL semantic facts.
    - FLOW-005 → SAST-003 (Layer 2 flow cannot depend on Layer 3 SAST). Rerouted: FLOW-005 exposes query API; SAST-003/004 consume that API.
  - **Acceptance criteria added** for `plsql-sqlsem`, `plsql-flow`, `plsql-facts`. Earlier §9.4 covered only IR/symbols/privileges.
  - **`AnalysisRun` struct expanded** to include `flow_summary`, `fact_store: FactStoreSnapshot`, and `artifacts: AnalysisArtifactManifest`. Without these in the canonical artifact, product surfaces would drift back to ad-hoc recomposition.
  - **Bindgen REF cursor contradiction fixed**: §13.3 type map row updated from `oracle::CursorStream<Row>` to `Unsupported(RefCursor)` matching §13.4 hard-parts text.
  - **Bindgen async wrapper contradiction fixed**: §13.2 output shape no longer hints at faked-async generation.
  - **Hazards table pipelined functions** corrected: emits `Unsupported(Pipelined)` diagnostic instead of `impl Stream`.
  - **R6 corpus directory list** updated to include `adversarial` + `db-fixtures`.
  - **R7 async runtime** rewritten to acknowledge daemon-mode and sync-first generated bindings.
  - **Naming and licensing tables** now list every crate (added `plsql-flow`, `plsql-facts`, plus `plsql-sqlsem` to licensing).
  - **`[DEFERRED]` status flag replaced** with `[FUTURE-PLAN]` / `[OUT-OF-SCOPE]` semantics. Updated D7, D12, D13, D14, D20, D9, and the §0 document convention.
  - **plan-lint enhanced**: whitelists quoted historical changelog blocks for banned-language scanning; adds component coverage matrix check; added PLAN-003 normalization bead for residual heading-number drift.
  - **v0.2 changelog entry sanitized** to remove residual "alpha/beta release wedge" language while preserving the historical note.
  - **D19 reworded** from "pre-1.0 until Layer 4 ships to a paying customer" to "GA is 1.0". The earlier wording implied customer-facing delivery before the full product existed, which contradicts §5's one-public-release principle.
  - **K1 mitigation refreshed**: explicit parser-backend tournament reference; this historical Java ANTLR fallback language was superseded by the 2026-06-28 retirement.
  - **K7 mitigation refreshed**: removed timeline hack ("ship Layer 4 within 4 months"); replaced with substantive differentiation (evidence quality, dynamic-SQL uncertainty, compiler/dictionary cross-checks, reproducible artifacts).
  - **§18.4 parser-backend packaging policy added**: historical operational details later superseded by the 2026-06-28 single-backend packaging decision.
  - **DBMS_ASSERT reclassified as sanitizer family**: renamed `dbms_assert_usage` to `sanitizer_usage`; added explicit classification (`SIMPLE_SQL_NAME`, `QUALIFIED_SQL_NAME`, `SCHEMA_NAME`, `ENQUOTE_LITERAL`, `SQL_OBJECT_NAME`, regexp/allowlist, numeric coercion, unknown); spelled out that presence is evidence, not safety proof.
- **2026-05-11 (round 3)** — **v0.5 DRAFT** — Third refinement round integrated from GPT Pro. Changes:
  - **Architectural bug fix:** `plsql-engine` moved from Layer 0 to Layer 2.5 (skeleton in Layer 0, implementation in Layer 2.5). Layer 0 cannot finish first if it contains a crate depending on parser+catalog+IR+symbols+privileges+sqlsem+depgraph.
  - **Added `plsql-facts`** (Layer 2): normalized fact store consumed by all product surfaces. Prevents drift across SAST/lineage/docs/bindgen that would inevitably appear if each re-walked raw IR independently.
  - **Added `plsql-flow`** (Layer 2): value flow, taint, constants, value sets, string shapes. Required for evidence-based SAST and credible dynamic-SQL analysis.
  - **Internal convergence gates** (§5): parser gate, catalog gate, semantic gate, graph gate, product-surface gate, GA gate. These are engineering quality checkpoints, NOT public release wedges. There is exactly one public release.
  - **Parser strategy as tournament** (D1): historical tournament framing; superseded by D2 and the 2026-06-28 retirement of the Java ANTLR spike.
  - **Oracle dialect feature registry**: `OracleFeature` enum + `FeaturePolicy` in `AnalysisProfile`. Version-gated handling of SQL BOOLEAN (23ai), VECTOR / SPARSE VECTOR / vector arithmetic (23ai/26ai), `PACKAGE RESETTABLE` (26ai), JSON-Relational Duality (23ai), SQL Macros, etc.
  - **PL/Scope tightening**: framed as compiler-derived comparison source, not a hidden prerequisite. Doctor explains compile/storage overhead implications.
  - **SQL Developer parser differential testing removed**: replaced with black-box Oracle compilation testing via `USER_ERRORS`, `ALL_DEPENDENCIES`, PL/Scope, and `DBMS_METADATA`.
  - **Bindings contradiction fix**: BG-008 (REF cursor inference) and BG-009 (pipelined Stream emission) reduced to `Unsupported` `BindingDiagnostic` entries; the inference + Stream work moved to future extensions `BG-X01`/`BG-X02`. Resolves contradiction between v0.4 §2.3 (REF cursor / pipelined non-goals) and §13 (beads implementing them).
  - **Column-level lineage precision tiers**: `ExactColumnLineage`, `ExpressionColumnLineage`, `TableScopedColumnUnknown`, `DynamicColumnUnknown`, `UnsupportedSqlShape`. New edge kinds: `DerivesColumn`, `ReadsUnknownColumnOfTable`, `WritesUnknownColumnOfTable`. `SELECT *` / `NATURAL JOIN` / view expansion never produce fake exact column edges.
  - **CI/CD lifecycle classifier** + `explain-lifecycle`: spec vs body, ALTER TYPE cascade, grants/revokes, synonym retargeting, MV refresh, editioned-object changes.
  - **Memory architecture**: `SymbolInterner` + typed IDs + AST eviction + compact graph adjacency + `plsql doctor memory`. Replaces aspirational budgets with implementation strategy.
  - **Daemon mode** (`plsqld`): optional local accelerator for developer workflows; CI uses immutable artifacts.
  - **`compare-oracle-deps` operation**: customer-facing delta report showing what Oracle dictionary sees vs what the engine sees vs why they differ. Demo killer.
  - **SAST evidence gates**: `required_facts()` + `minimum_completeness()`; rules emit `RuleSkippedDiagnostic` instead of weak findings when evidence is missing.
  - **Support-bundle hardening**: optional age/PGP encryption, literal classifier, per-bundle salt, redaction manifest, never include raw cache.
  - **Trivadis license correction**: Cop CLI is CC BY-NC-ND 3.0 (not Apache-2.0); only the coding-guidelines repo is Apache-2.0. ZPA is LGPL-3.0. Don't vendor either.
  - **D9 contradiction fixed**: subsetter masking interface allowed internally, but no public release with stub masking advertised as anonymization.
  - **`plan-lint` tool**: validates plan.md structure (heading-number monotonicity, ToC anchors, duplicate bead IDs, missing dependencies, banned release-wedge language).
  - **v0.4 residue cleaned**: "FIRST PRODUCT SURFACE" / "LATER PRODUCT SURFACES" / "release-deferred" strings still present in §5 dependency graph and §6.2.1 workspace removed.
- **2026-05-11 (correction)** — **v0.4 DRAFT** — Removed the release-wedge framing that v0.2 + v0.3 had let slip in. The `planning-workflow` skill warns against skeleton-first / incremental coding ("one big comprehensive plan beats incremental coding") and the operator had stated upfront that MVP/timeline/wave language is forbidden. The "first product surface" / "release-deferred" labels were that pattern under a different name. Specific changes:
  - §5 dependency graph: removed the "Release wedge" sub-table; added clarification that dependency ordering is not release packaging
  - §1.1 purpose: rewritten to state "the first release ships the full working product" with all in-scope components converging together
  - §2.1 scope table: removed "(first product surface)" and "(release-deferred)" labels from every component
  - §2.3 reframed from "deferred — revisit after first product surface ships" to "not in scope of this plan"; merged the v0.2 §2.2 separate-projects list with v0.3 §2.3 deferrals; clarified that listed items belong to other plans or are out of charter
  - §11–§15 section headers: removed "(first product surface)" / "(release-deferred to v0.4+)" suffixes
  - §16 (subsetting): reframed from "DEFERRED PRODUCT" to "OUT OF SCOPE — routed to a separate future plan"; section retained as a placeholder so the bead seeds are not lost
  - §23 release beads: `PLSQL-RELEASE-001` is now a single bead that closes when every other bead in the plan closes; `PLSQL-RELEASE-002` tracks customer pilot outcomes against the same product, not a product subset
- **2026-05-11 (round 2)** — **v0.3 DRAFT** — Second refinement round integrated from GPT Pro Extended Reasoning. Changes:
  - Added `plsql-engine` canonical pipeline orchestrator (`AnalysisRequest` / `AnalysisRun`) preventing architectural drift across consumers
  - Added Oracle PL/Scope (`plsql-plscope` inside `plsql-catalog`) as a compiler-native validation/enrichment source
  - Introduced `AnalysisProfile` in `plsql-core` consolidating Oracle version, compatibility, current schema/user/edition, `PLSQL_CCFLAGS`, NLS, enabled roles, DB-link policy
  - Conditional compilation upgraded from "flag collection" to true **preprocessing** that emits the source view Oracle would compile
  - Added `CompletenessReport` as first-class output emitted by every `AnalysisRun`
  - Revised node identity: `LogicalObjectId` + `ObjectRevisionId` + optional `PersistentObjectId`; rename is no longer silently merged (`classify-rename` operation added)
  - Added `plsql-sqlsem` crate (dedicated embedded-SQL semantic model) — unblocks credible column-level lineage
  - Extended `plsql-catalog`: object status, edition, last DDL, dependency rows, scheduler jobs, editioning views, `DBMS_METADATA` DDL/XML, capability negotiation with grant-suggestion diagnostics
  - Parse-quality metrics replace single parse-success rate (clean rate, recovered rate, skipped-token ratio, top-level recognition)
  - Added `explain` command for edges/nodes/paths (productized provenance + evidence)
  - SAST: dedup QUAL001/QUAL002, narrow SEC002, opt-in SEC007, `default_enabled` trait, stable `FindingFingerprint`, inline-comment + config suppressions
  - Bindings: pluggable date/time backend; corrected `TIMESTAMP WITH TIME ZONE` / `WITH LOCAL TIME ZONE` mappings; PL/SQL `BOOLEAN` vs SQL `BOOLEAN` distinction; fixed BG-000/BG-001 dependency ordering
  - CI/CD: predict modes (`source-only`, `catalog-aware`, `live-snapshot`)
  - Added §18.11 `RedactionPolicy` (none/identifiers/snippets/strict) with strict default for support bundles
  - Added DB fixture strategy `corpus/db-fixtures/` with install scripts + golden outputs
  - Added D20 (LSP/IDE deferred); `plsql-output` schemas designed to not preclude LSP
  - Stale-reference cleanup: glossary §24→§26; `DEP-009/010` moved from `plsql-render` to component-owned per R5; naming section lists all current crates; subsetter `SUB-008` no longer ships masking stubs as anonymization
  - Dictionary dependency cross-check (`PLSQL-DEP-014`) added to validation strategy
- **2026-05-11 (round 1)** — **v0.2 DRAFT** — First refinement round integrated from GPT Pro Extended Reasoning. Changes:
  - Added Layer 1.5 (Oracle Context: `plsql-catalog` + `plsql-project`)
  - Added Layer 2 component `plsql-privileges`
  - Added R20 (parser backend isolation)
  - Reworked R2 (backend abstraction), R5 (output contracts split), R13 (uncertainty taxonomy generalized), R14 (caching foundation-level), R16 (licensing corrected)
  - **CRITICAL fix:** §15 CI/CD `verify` no longer claims rollback (Oracle DDL implicitly commits) — added isolated-target requirement + `--dangerously-verify-in-place` hard guard
  - CST + token-tape lossless contract; AST is semantic (not formatting-lossless)
  - `UnknownReason` taxonomy + `DynamicSqlEvidence` structured evidence model
  - Stable node identity with overload signatures in dep graph
  - SAST precision tiers; rule pack tightened; "empty lane" claim softened (ZPA/SonarQube acknowledged)
  - Bindings: sync-first via `OracleExecutor` trait; `Defaulted<T>` for Omit/Null/Value distinction
  - Lineage: `classify-change` operation; diff-aware `what-breaks` (Git diff / before-after / DDL / catalog-snapshot-diff)
  - New §17: Oracle-specific semantic hazards (formal hazard inventory)
  - Corpus license discipline: per-file manifest + CI gate
  - Subsetting demoted from Layer 5 to "future product" — separate plan required
  - (Historical note: v0.2 introduced a partial-release framing that was later rejected and removed in v0.4/v0.5/v0.6.)
  - K12-K17 added to risk table
  - Factual corrections: Manta acquired 2023-10-24 (not August), "PL/SQL SAST is empty" softened to "underserved"
- **2026-05-11** — v0.1 DRAFT — Plan authored from strategy session.

---

## Next actions

This plan has already been through nine refinement rounds and is ready for the next refinement pass per the `planning-workflow` skill:

1. Paste this entire document into GPT Pro Extended Reasoning with the canonical "review and revise" prompt
2. Integrate revisions via Claude Code with the canonical "integrate revisions" prompt
3. Repeat 1–3 more rounds until a full pass yields only minor wording or dependency-hygiene edits
4. Optionally blend with Gemini 3.1 Pro Deep Think + Grok 4 Heavy outputs
5. Convert to beads via the `beads-workflow` skill once steady-state is reached
6. Resolve `[OPEN]` decisions in §21 (the founder's call, captured in the decision log when made)

Until then, no implementation beads should be created. The plan is the source of truth; deviations require a plan amendment first.