# Proposal: single-react-mysql-readonly-tool

## Problem

阶段 1 已冻结 `query_mysql` 的逻辑请求和有界结果契约，但当前仓库没有一个能把 SQL 安全地转换为可执行查询的实现。直接把 Agent 生成的 SQL 交给 JDBC 会允许写操作、元数据探测、通配符泄漏、allowlist 绕过和无界结果。

## Proposed change

- 引入 JSqlParser 4.6，解析单条 SQL 并对保守的 SELECT 子集执行 fail-closed AST 校验。
- 增加逻辑数据源定义和静态 `schema -> table -> column` 精确 allowlist；Agent 只能传逻辑数据源 ID。
- 增加参数绑定、占位符数量校验、函数 allowlist、显式列校验、JOIN/过滤/分组/排序字段校验和受控 LIMIT。
- 增加 JDBC 只读执行器：只使用配置映射的 DataSource，设置 `readOnly`、`PreparedStatement`、`setMaxRows`、查询超时，并在 Run 取消时中止执行。
- 增加 MySQL 结果 projector：限制行数、单元格和总 UTF-8 字节，脱敏敏感列，产生 `MysqlToolResult` 和 `NO_EVIDENCE`。
- 通过阶段 3A `ToolBoundary` 接入 canonical invocation store、Run budget、生命周期、`evidence_status` 和框架 `tool_call_id`。
- 把 `scripts/query_mysql.py` 收敛为仅允许 SELECT/受控 SHOW 的只读查询脚本，移除默认外部连接参数和 commit 分支；凭据与连接信息全部从环境变量读取。

## Scope

### In scope

- SQL AST validator and validated query plan.
- Static logical data-source/allowlist model.
- JDBC read-only executor abstraction and implementation.
- MySQL result projector and ToolBoundary adapter.
- Security, truncation, timeout/cancellation, no-evidence and boundary tests.
- Query script safety cleanup required by the ISS-014 security prerequisite.

### Out of scope

- Diagnosis Agent cutover or public Chat/AIOps/SSE changes.
- Querying the application's own persistence database through the Agent-facing Tool.
- Metadata discovery (`SHOW TABLES`, `SHOW COLUMNS`, `DESCRIBE`, `information_schema`).
- Tenant/row-level authorization, dynamic allowlists, arbitrary SQL functions, real production business datasource provisioning.

## Frozen SQL subset

- One `SELECT` statement only.
- Explicit projection columns; `COUNT(*)` is the only star exception.
- `INNER JOIN` and `LEFT JOIN`, normal predicates, `GROUP BY`, `HAVING`, `ORDER BY` and parameter placeholders.
- No `WITH`, subquery, `UNION`, window function, `CROSS JOIN`, write statement, metadata query, transaction control, dangerous function, or unknown AST node.

## Constraints and risks

- Parser acceptance is not authorization: every table and column used by projection, predicates, joins, grouping and ordering must pass the independent allowlist.
- Unknown data source, schema, table, column, function, placeholder mismatch or parser failure fails closed before JDBC execution.
- JDBC row/cell/byte limits are enforced in addition to ToolBoundary limits; oversized results are projected with `truncated=true` or become a safe error when no valid bounded result can be produced.
- The adapter is not wired into the existing public runtime in this stage; later Diagnosis Agent work will select it through the internal Harness application use case.

## Acceptance direction

- Valid explicit-column SELECT and `COUNT(*)` pass AST and allowlist validation.
- Write statements, metadata, wildcard projection, nested/compound queries, unknown AST, allowlist bypass and placeholder mismatch are rejected without executor invocation.
- JDBC executor uses read-only prepared statements, max rows, timeout and cancellation.
- Agent receives only bounded `MysqlToolResult`; raw JDBC rows remain Harness-only canonical data.