docs(plans): phased plan for de-vendoring the SQL-safety kernel (18.1)

[devopam]

Summary

Plan-first deliverable for roadmap 18.1 — replace the vendored crystaldba/postgres-mcp SQL-safety kernel (src/mcpg/_vendor/sql/) with a first-party implementation MCPg owns, removing the last vendored runtime code.

Recon against the tree found the effort is smaller and safer than the roadmap entry assumed:

• bind_params.py / extension_utils.py / index.py (~1,114 LOC) are dead — no consumer outside _vendor/ — so they're deleted, not rebuilt.
• The real rebuild is safe_sql.py (pglast allowlist validator) + sql_driver.py (SqlDriver / DbConnPool / obfuscate_password).
• The consumer seam is 4 names across ~74 files, so the swap is stable-seam + a mechanical import rewrite; tool-surface / return-shape snapshots stay byte-identical.

The plan proposes 2 large PRs with a mandatory security-review gate between them:

1. Additive — land first-party mcpg.sql (re-architected into driver / allowlist-as-data / safety) + port the 760-LOC adversarial suite against it, proving parity while _vendor/ stays live.
2. Swing — rewrite the 74 imports, delete _vendor/ + tests/vendor/ wholesale, remove the 5 quality-gate carve-outs (so the allowlist finally gets coverage + mypy --strict + bandit), regen the module map, supersede ADR-0001 with a new ADR.

Security-review gate (before PR 2): differential accept/reject verdict test old-vs-new (0 divergence), allowlist audit vs threat model, fuzz pass, /security-review, threat-model note in the new ADR.

Roadmap linkage

Advances roadmap row: 18.1 (planning artifact; linked from docs/feature-shortlist.md §18).

Checklist

• Docs-only; no code / snapshot changes
• Roadmap row cited (18.1) + plan linked from the shortlist
• No hand-edits to src/mcpg/_vendor/

🤖 Generated with Claude Code

---

Generated by Claude Code

Summary by Sourcery

Document a phased plan to replace the vendored SQL-safety kernel with a first-party implementation and link it into the feature roadmap.

Documentation:

• Add a detailed plan document for de-vendoring the SQL-safety kernel, including design, phased PRs, security review gate, risks, and definition of done.
• Update the roadmap feature shortlist entry for item 18.1 to reference the new plan and refine scope based on codebase reconnaissance.

[gemini-code-assist-2]

Code Review

This pull request introduces a comprehensive plan for de-vendoring the SQL-safety kernel and replacing it with a first-party implementation. It updates the feature shortlist with a phased plan link and adds a detailed planning document (docs/plans/devendor-sql-kernel.md) outlining the target design, re-architecture, security-review gates, and testing strategy. No review comments were provided, so there is no feedback to address.

[sourcery-ai]

Hey - I've left some high level feedback:

• The plan doc is very detailed; consider adding a short TL;DR section up top (bulleted timeline + key constraints) so future readers can quickly orient before diving into the full narrative.
• In the "Security-review gate" section, it may help to explicitly assign ownership (role/team) and success criteria for each step (e.g., who runs /security-review, who signs off on the allowlist audit) so this process is operationally actionable rather than aspirational.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The plan doc is very detailed; consider adding a short TL;DR section up top (bulleted timeline + key constraints) so future readers can quickly orient before diving into the full narrative.
- In the "Security-review gate" section, it may help to explicitly assign ownership (role/team) and success criteria for each step (e.g., who runs `/security-review`, who signs off on the allowlist audit) so this process is operationally actionable rather than aspirational.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}