SuperBizAgent-java/devflow/projects/2026-07-21-single-react-mysql-readonly-tool/decisions.md

Decisions: single-react-mysql-readonly-tool

Discover status

• Checkpoint: Discover
• Capability source: sm-flow with local ISS-014, OpenSpec contracts, existing JDBC dependency/configuration and JSqlParser 4.6 already present in the local Maven cache.
• Scale: complex, because this stage combines AST policy, authorization, JDBC resource limits, projection, and security cleanup.

Evidence-driven findings

1. MysqlToolRequest and MysqlToolResult are already frozen under harness.tool.contract; no public DTO change is needed.
2. The project already has MySQL JDBC/JPA dependencies, but no Agent-facing external read-only executor or SQL policy.
3. JSqlParser 4.6 is available in the local Maven cache and exposes CCJSqlParserUtil, Select, PlainSelect, Table, Column, Function, JdbcParameter and visitor adapters compatible with Java 17.
4. The current application datasource points to the Agent persistence database; the new Tool must use an independently configured logical datasource map and must not reuse that datasource implicitly.
5. scripts/query_mysql.py currently defaults host/port/user values and contains a non-SELECT commit branch. This violates the ISS-014 security prerequisite and will be changed to read-only, environment-only behavior.

Question pool

Dimension	Question	Mode	Conclusion	Status
SQL language	Which SQL subset is executable?	evidence-driven	One SELECT, explicit columns, INNER/LEFT JOIN, predicates/group/order, parameter placeholders and allowlisted aggregates.	resolved
Security	How is authorization decided?	evidence-driven	Independent exact schema/table/column allowlist; parser acceptance alone is insufficient.	resolved
Data source	Can the Agent pass JDBC coordinates?	evidence-driven	No. Only logical data_source IDs are accepted; connection properties remain configuration/Secret data.	resolved
Execution	Which JDBC controls are mandatory?	evidence-driven	PreparedStatement, readOnly connection, setMaxRows, query timeout and Run cancellation.	resolved
Metadata	Can the Tool discover tables/columns?	evidence-driven	No. SHOW/DESCRIBE/information_schema are rejected.	resolved
Compatibility	Does this cut over public runtime now?	evidence-driven	No. Add internal adapter/executor; Diagnosis Agent integration is stage 4.	resolved

User-confirmed direction

• Use the frozen MysqlToolRequest/MysqlToolResult contract.
• Reuse the existing ToolBoundary and canonical invocation store.
• Keep stage boundaries serial: archive and commit 3C before stage 4.
• Do not pause for routine apply/archive/commit confirmation.

Pre-apply research

Existing implementations and dependencies

• src/main/java/com/superbiz/agent/harness/tool/contract/MysqlToolRequest.java
• src/main/java/com/superbiz/agent/harness/tool/contract/MysqlToolResult.java
• src/main/java/com/superbiz/agent/harness/tool/boundary/ToolBoundary.java
• src/main/java/com/superbiz/agent/harness/tool/adapter/QueryLogsToolAdapter.java
• src/main/resources/application.yml
• pom.xml (mysql-connector-j already present; add JSqlParser 4.6)
• scripts/query_mysql.py

New classes

• MysqlToolLimits
• MysqlDataSourceDefinition / allowlist value objects
• MysqlQueryPlan
• MysqlSqlValidator
• MysqlReadOnlyExecutor and JDBC implementation
• MysqlResultProjector
• MysqlToolAdapter

Risk controls

• Do not create a generic plugin/DSL layer.
• Do not use regex or startsWith as SQL authorization.
• Fail closed on parser/visitor uncertainty.
• Keep raw result canonical-only and expose only bounded projection.

Commit checkpoint preparation

• Proposal scope, design choices, frozen SQL subset, security script cleanup and acceptance scenarios are ready for Commit artifact generation.

Commit audit

• Capability source: sm-flow and local OpenSpec CLI.
• OpenSpec strict validation: passed for single-react-mysql-readonly-tool.
• Cross-artifact alignment:
  • brief goals/non-goals -> proposal scope: aligned.
  • proposal SQL/security boundaries -> design architecture: aligned.
  • design validator/executor/projector decisions -> spec requirements: aligned.
  • spec scenarios -> tasks for dependency, policy, JDBC, projection, adapter and verification: aligned.
• Interface impact: L2 internal Harness tool/adapter plus JSqlParser dependency and query-script behavior; no public protocol changes.
• Preflight risk accepted: parser ambiguity, datasource isolation, driver cancellation behavior and sensitive result values all fail closed or remain Harness-only.

Commit gate

• proposal, design, specs and tasks exist.
• strict OpenSpec validation passes.
• all evidence-driven questions are resolved.
• no unresolved interface decision remains.
• .committed marker created for Apply.

Apply result

• Added JSqlParser 4.6 and fail-closed MysqlSqlValidator.
• Added immutable logical datasource/allowlist/limit/query-plan/raw-result models and independent MysqlToolProperties binding.
• Added JdbcMysqlReadOnlyExecutor with read-only connection, PreparedStatement binding, query timeout, max rows, cell/result limits and Run cancellation callback.
• Added MysqlResultProjector with sensitive-column redaction, row/cell/total UTF-8 bounds and NO_EVIDENCE.
• Added MysqlToolAdapter through the existing ToolBoundary; invalid SQL is rejected before database execution.
• Replaced scripts/query_mysql.py with environment-only, read-only transaction behavior and pre-connect write/metadata rejection.

Apply conflicts and corrections

• COUNT(*) is represented by JSqlParser as an AllColumns parameter in this version; the visitor was corrected to permit only the explicit COUNT(*) exception.
• JDBC metadata access cannot be used as a checked-exception stream method reference; the implementation uses an explicit column loop.
• No OpenSpec/design conflict was found; both corrections were implementation details.

Archive result

• Apply tasks complete and .archive-ready created.
• OpenSpec archived at openspec/changes/archive/2026-07-21-single-react-mysql-readonly-tool.
• Main capability specification added at openspec/specs/mysql-readonly-tool/spec.md.
• Stage 4 may consume the internal adapter only after this stage is committed.