feat(usable): package gui-host validation snapshot

Co-Authored-By: Paperclip <noreply@paperclip.ing>

FAILURE_PATH_EVIDENCE_SAMPLE.md

@@ -0,0 +1,150 @@
+# PostgreSQL / MySQL Failure-Path Evidence Sample
+
+日期：2026-03-28  
+作者：Senior Backend Engineer  
+用途：给 QA / CTO 一份可直接复制改值的 failure-path 记录样例。
+
+## 使用方式
+
+- 本文件是“填写示例”，不是执行证据本身。
+- 只有把其中的时间、宿主机、二进制路径、commit、命令输出替换为真实值后，才能回填到 `USABLE_EVIDENCE_LEDGER.md` 或 issue 评论中。
+- 正式场景列表与命令来源仍以 `FAILURE_PATH_EVIDENCE_TEMPLATE.md` 为准。
+
+## Sample A: PostgreSQL Wrong Password
+
+### `PG-CONN-AUTH-001`
+
+- Date (UTC): `2026-03-28T14:10:00Z`
+- Operator: `qa-engineer`
+- Host: `qa-host-01`
+- Binary Path: `./target/release/dbtool`
+- Binary Version: `0.1.0`
+- Commit SHA: `<replace-with-real-sha>`
+- Branch: `<replace-with-real-branch>`
+- Driver: `postgres`
+- Scenario ID: `PG-CONN-AUTH-001`
+- Command:
+
+```bash
+export DBTOOL_PASSWORD=wrong-password
+./target/release/dbtool connect --driver postgres --host 127.0.0.1 --port 55432 --database dbtool_demo --username dbtool --password-env DBTOOL_PASSWORD --result-format json
+```
+
+- Exit Code: `2`
+
+Output (excerpt):
+
+```json
+{
+  "status": "error",
+  "operation": "connect",
+  "state": "error",
+  "error": {
+    "operation": "connect",
+    "kind": "authentication",
+    "message": "postgres authentication failed"
+  }
+}
+```
+
+Verdict:
+
+- Expected: `status=error`, `state=error`, `error.kind=authentication`, 无密码泄露
+- Actual: JSON envelope 返回 `authentication`，未回显 password env 的实际值
+- Result: `pass`
+
+## Sample B: MySQL Unreachable Port
+
+### `MY-CONN-NET-001`
+
+- Date (UTC): `2026-03-28T14:18:00Z`
+- Operator: `qa-engineer`
+- Host: `qa-host-01`
+- Binary Path: `./target/release/dbtool`
+- Binary Version: `0.1.0`
+- Commit SHA: `<replace-with-real-sha>`
+- Branch: `<replace-with-real-branch>`
+- Driver: `mysql`
+- Scenario ID: `MY-CONN-NET-001`
+- Command:
+
+```bash
+export DBTOOL_PASSWORD=dbtool
+./target/release/dbtool connect --driver mysql --host 127.0.0.1 --port 59998 --database qa_demo --username dbtool --password-env DBTOOL_PASSWORD --result-format json
+```
+
+- Exit Code: `2`
+
+Output (excerpt):
+
+```json
+{
+  "status": "error",
+  "operation": "connect",
+  "state": "error",
+  "error": {
+    "operation": "connect",
+    "kind": "connection",
+    "message": "connection failed: Connection refused (os error 111)"
+  }
+}
+```
+
+Verdict:
+
+- Expected: `status=error`, `state=error`, `error.kind=connection`
+- Actual: JSON envelope 返回 `connection`，符合不可达端口预期
+- Result: `pass`
+
+## Sample C: PostgreSQL Bad SQL
+
+### `PG-QUERY-SQL-001`
+
+- Date (UTC): `2026-03-28T14:25:00Z`
+- Operator: `qa-engineer`
+- Host: `qa-host-01`
+- Binary Path: `./target/release/dbtool`
+- Binary Version: `0.1.0`
+- Commit SHA: `<replace-with-real-sha>`
+- Branch: `<replace-with-real-branch>`
+- Driver: `postgres`
+- Scenario ID: `PG-QUERY-SQL-001`
+- Command:
+
+```bash
+export DBTOOL_PASSWORD=dbtool
+./target/release/dbtool query --driver postgres --host 127.0.0.1 --port 55432 --database dbtool_demo --username dbtool --password-env DBTOOL_PASSWORD --file examples/sql/postgres/failing_query.sql --result-format json
+```
+
+- Exit Code: `2`
+
+Output (excerpt):
+
+```json
+{
+  "status": "error",
+  "operation": "query",
+  "state": "error",
+  "error": {
+    "operation": "query",
+    "kind": "query",
+    "message": "query failed: relation does not exist"
+  }
+}
+```
+
+Verdict:
+
+- Expected: `status=error`, `state=error`, `error.kind=query`
+- Actual: JSON envelope 返回 `query`，错误定位在 SQL 执行阶段
+- Result: `pass`
+
+## 回填规则
+
+- 一次执行至少保留：
+  - 完整命令
+  - 退出码
+  - 关键 JSON 片段
+  - 实际 commit / branch
+- 若输出和样例文案不同，只要 `status`、`state`、`error.kind` 与场景预期一致，可以判为 `pass`。
+- 若 `error.kind` 偏离预期，应优先回填到 issue，并视为 backend contract 回归候选。