@ironbee-ai/cli 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.9.3 (2026-05-12)
+
+### Features
+
+* **backend:** support db and o11y domains in the backend platform ([#13](https://github.com/ironbee-ai/ironbee-cli/issues/13)) ([6801ebe](https://github.com/ironbee-ai/ironbee-cli/commit/6801ebe9204cafd4ffccbc305418f8c284db5ba6))
+
+## 0.9.2 (2026-05-11)
+
+### Features
+
+* **backend:** support log domain in the backend platform ([#11](https://github.com/ironbee-ai/ironbee-cli/issues/11)) ([4512275](https://github.com/ironbee-ai/ironbee-cli/commit/4512275b5f90c501481f4b07c13057fea475e3fb))
+
 ## 0.9.1 (2026-05-11)
 
 ### Bug Fixes

package/README.md

@@ -372,7 +372,7 @@ When the agent tries to complete a task, IronBee runs these checks:
    - **Browser cycle**: navigate, screenshot, accessibility snapshot, console check (all-of)
    - **Node cycle**: connect; then either probe path (`(put-tracepoint | put-logpoint | put-exceptionpoint) AND get-probe-snapshots`) OR log path (`get-logs`)
 4. **Does a verdict exist?** — The agent must submit a single verdict carrying evidence for every active cycle via `ironbee hook submit-verdict`.
-5. **Is the verdict valid?** — Per active cycle: browser fields (pages_tested, console_errors, network_failures) and/or node fields (backend_node_processes_connected, backend_node_probes_set / backend_node_log_errors).
+5. **Is the verdict valid?** — Per active cycle: browser fields (pages_tested, console_errors, network_failures) and/or node fields (node_processes_connected, node_probes_set / node_log_errors).
 6. **Pass or fail?** — `status: "pass"` is honored only if every active cycle's evidence backs the claim. The gate overrides to fail if it doesn't.
 7. **Retry limit** — After `maxRetries` failed attempts (default 3, single global counter), the agent is allowed to complete but must report unresolved issues.
 
@@ -419,23 +419,23 @@ On pass after a previous fail, include a `fixes` array describing what was fixed
 }
 ```
 
-For a **node-cycle** verdict (probe path), use the `backend_node_*` fields instead of (or alongside) the browser fields:
+For a **node-cycle** verdict (probe path), use the `node_*` fields instead of (or alongside) the browser fields:
 
 ```json
 {
   "session_id": "<your-session-id>",
   "status": "pass",
   "checks": ["POST /api/orders returned 201", "tracepoint at handler.ts:42 fired once"],
-  "backend_node_processes_connected": ["pid:12345 (next-server)"],
-  "backend_node_probes_set": [
+  "node_processes_connected": ["pid:12345 (next-server)"],
+  "node_probes_set": [
     { "type": "tracepoint", "location": "src/api/orders.ts:42", "triggered": true }
   ],
-  "backend_node_probe_snapshots_collected": 1,
-  "backend_node_log_errors": []
+  "node_probe_snapshots_collected": 1,
+  "node_log_errors": []
 }
 ```
 
-If both cycles are active, populate browser fields **and** `backend_node_*` fields in the same verdict — both cycles' pass criteria must hold for the gate to honor `status: "pass"`.
+If both cycles are active, populate browser fields **and** `node_*` fields in the same verdict — both cycles' pass criteria must hold for the gate to honor `status: "pass"`.
 
 The agent must submit a verdict after **every** verification attempt — both pass and fail. File edits are blocked until a verdict is submitted after using devtools tools.
 

package/dist/clients/claude/hooks/require-verdict.js

@@ -40,7 +40,7 @@ async function run(projectDir) {
     if ((0, actions_1.hasToolCallsSinceLastVerdict)(actionsFile)) {
         process.stderr.write(`BLOCKED: You used verification tools (browser-devtools / node-devtools / backend-devtools) but did not submit a verdict. You MUST submit a verdict (pass or fail) before editing code.
 
-Submit your verdict first (include cycle-appropriate fields — browser fields for bdt_*, backend_node_* for ndt_*, backend_endpoints_called/backend_response_statuses for bedt_*):
+Submit your verdict first (include cycle-appropriate fields — browser fields for bdt_*, node_* for ndt_*, backend_endpoints_called/backend_response_statuses for bedt_*):
   echo '{"session_id":"${sessionId}","status":"fail","checks":[...],"issues":["describe what failed"], ...}' | ironbee hook submit-verdict
 
 Then you can edit code to fix the issues.

package/dist/clients/claude/platforms/command-verify.backend.md

@@ -4,27 +4,50 @@
 
 If the project has the backend protocol cycle enabled (`ironbee backend enable` once at setup) and your edits touch matching paths (e.g. `server/**`, `api/**`, `routes/**`, `controllers/**`), the Stop hook also enforces a Backend cycle. The same `verification-start` covers every active cycle; the same verdict file carries fields for all of them.
 
-This cycle is **runtime- and language-agnostic** — it works for Node, Java, Python, Go, Rust, Ruby, .NET, PHP, Elixir, Kotlin, Scala. The agent makes real protocol calls (HTTP / gRPC / GraphQL / WebSocket) against the running service and inspects the responses; it never attaches to a process.
+This cycle is **runtime- and language-agnostic** — it works for Node, Java, Python, Go, Rust, Ruby, .NET, PHP, Elixir, Kotlin, Scala. The agent makes real protocol calls (HTTP / gRPC / GraphQL / WebSocket) against the running service, inspects logs, OR reads database state; it never attaches to a process.
 
 ### Mode behavior (backend cycle)
-- **default** (no arg or `default`): call only the endpoints your diff touched. Map each changed file → the route(s) / handler(s) / RPC method(s) it exposes → call them, then chain enough follow-up calls to verify side effects.
-- **full**: exercise every endpoint reachable from files matching `backend.verifyPatterns`, not just the changed files. Cover the success path, at least one error path, and any auth-gated variant for each.
+- **default** (no arg or `default`): exercise the endpoints your diff touched via ONE of the three evidence paths (protocol-call, log evidence, or DB evidence — see below). Map each changed file → the route(s) / handler(s) / RPC method(s) / table(s) it exposes, then either call them yourself and chain follow-ups to verify side effects, OR set up log capture, OR inspect database state directly.
+- **full**: cover every endpoint reachable from files matching `backend.verifyPatterns`, not just the changed files. Cover the success path, at least one error path, and any auth-gated variant for each. For schema / migration changes, verify every affected table.
 - `visual` / `functional`: browser-only modes; this cycle behaves as `default` when they are passed.
 
 ### Steps (additive to the browser flow above)
+
+The cycle is satisfied by ANY ONE of three evidence paths: protocol-call (you drive the request), log-evidence (something else drives it; you read the logs), or DB-evidence (you inspect database state). Pick whichever fits the task — multiple can be combined.
+
 1. **Confirm the backend service is running** (the user's dev server / Docker compose / k8s port-forward / …). Don't start the service yourself — ask the user if it's not obvious.
-2. **Identify the affected endpoint(s)**. Map your code change to wire-level addresses (URL, gRPC service+method, GraphQL operation, WebSocket path).
-3. **Make a real protocol call** with the matching tool:
+2. **Identify the affected layer** — wire endpoint, log output, and/or database state. Map your code change to its observable side(s).
+3. **Exercise ONE or more evidence paths**:
+
+   **Path A — Protocol-call (you drive the request):**
    - `mcp__backend-devtools__bedt_request_http` — HTTP/1.1 + HTTP/2 (ALPN auto-negotiates).
    - `mcp__backend-devtools__bedt_request_grpc` — unary + 3 streaming modes; `.proto` text or descriptor.
    - `mcp__backend-devtools__bedt_request_graphql` — query/mutation/persisted query.
    - `mcp__backend-devtools__bedt_request_websocket-open` then `bedt_request_websocket-send` / `bedt_request_websocket-receive` / `bedt_request_websocket-close` for stateful WS sessions.
    - `mcp__backend-devtools__bedt_request_replay` — re-issue a captured curl command or HAR entry.
-4. **Inspect the response** — `status`, body, headers, `traceId`. **4xx/5xx and gRPC non-OK are normal results, not transport errors.** Decide PASS/FAIL based on what the test actually requires.
-5. **Chain follow-up calls** to verify side effects (POST then GET, set then list, etc.). Use `bedt_request_set-default-headers` for auth tokens (host-scoped), `bedt_request_set-cookies` for session state.
-6. **Submit verdict** including `backend_*` fields. If browser and/or node cycles are also active, include their fields in the SAME verdict — do not submit two verdicts.
+   - **Inspect the response** — `status`, body, headers, `traceId`. **4xx/5xx and gRPC non-OK are normal results, not transport errors.** Decide PASS/FAIL based on what the test actually requires.
+
+   **Path B — Log evidence (an external driver hits the endpoint; you read the logs):**
+   - `mcp__backend-devtools__bedt_log_register-source` — register the running service's log destination (`type: "file"` + `path`, `type: "docker"` + `container`, or `type: "kubernetes"` + `pod`).
+   - `mcp__backend-devtools__bedt_log_read` / `bedt_log_read-multi` — point-in-time read with filters (`tail`, `since`/`until`, `pattern`, `level`, `parseJson` + `jsonFilter`, `contextBefore`/`contextAfter`, `select`, `coalesce`).
+   - `mcp__backend-devtools__bedt_log_follow` + `bedt_log_get-followed` (and `bedt_log_stop-follow`) — streaming follow when you need to capture lines that emit AFTER you trigger.
+   - **Verify the lines match the expectation** — error gone, expected line present, trace-id chained through, no unexpected ERROR-level entries.
+
+   **Path C — DB evidence (you inspect database state directly):**
+   - `mcp__backend-devtools__bedt_db_connect` — open a named connection (`type: "postgres" | "mysql" | "sqlite"`, prefer `connectionStringEnv` over inline `connectionString`, default `allowWrites: false`).
+   - `mcp__backend-devtools__bedt_db_list-tables` / `bedt_db_describe-table` — discover schema; great for migration verification.
+   - `mcp__backend-devtools__bedt_db_query` — run a read query (parametrized; readonly mode is enforced server-side).
+   - `mcp__backend-devtools__bedt_db_snapshot` (+ `bedt_db_diff`) — pre/post state diff so you can prove a code path changed exactly the rows it should have.
+   - `mcp__backend-devtools__bedt_db_watch-changes` + `bedt_db_get-changes` — streaming change capture for verifying writes triggered by a protocol call or external driver.
+   - `mcp__backend-devtools__bedt_db_transaction-begin/-commit/-rollback` — scope seed data to one test so it doesn't leak.
+   - `bedt_db_disconnect` to clean up (optional — session teardown handles it).
+4. **Chain follow-ups across paths** — protocol-call → DB read to verify writes landed, protocol-call → log read to verify trace-id chained, etc. Use `bedt_request_set-default-headers` for auth tokens (host-scoped), `bedt_request_set-cookies` for session state on Path A.
+5. **Trace correlation (optional, `o11y_*` primitives):** IronBee already pins the verification cycle's traceId on every backend tool call via `_metadata.traceId` (outranks any session pin), so the orchestrator's correlation root is authoritative. Use `bedt_o11y_get-trace-context` to read it, then pass it to `bedt_log_read { pattern: "<traceId>" }` to slice logs for one flow. `bedt_o11y_new-trace-id` / `bedt_o11y_set-trace-context` are available when you want to anchor a flow under an explicit id (e.g. integration-test runs).
+6. **Submit verdict** including the fields matching the path(s) you exercised. If browser and/or node cycles are also active, include their fields in the SAME verdict — do not submit two verdicts.
 
 ### Verdict (backend-cycle fields)
+
+Protocol-call path:
 ```json
 {
   "session_id": "...",
@@ -39,7 +62,27 @@ This cycle is **runtime- and language-agnostic** — it works for Node, Java, Py
 }
 ```
 
-`backend_endpoints_called` is the only required field for this cycle. `backend_response_statuses` and `backend_traces_collected` are optional but strongly recommended — same order as `backend_endpoints_called`. There is no automatic pass-criteria override on this cycle: if `status: pass` and the evidence is structurally valid, the gate honors it.
+Log-evidence path:
+```json
+{
+  "session_id": "...",
+  "status": "pass",
+  "checks": ["api-server logged 'order 42 created' on POST /api/orders", "no ERROR-level lines after the change"],
+  "backend_log_sources_read": ["api-server"]
+}
+```
+
+DB-evidence path:
+```json
+{
+  "session_id": "...",
+  "status": "pass",
+  "checks": ["users table has new email_verified column with default false", "row count unchanged after migration"],
+  "backend_db_connections_read": ["app"]
+}
+```
+
+At least one of `backend_endpoints_called`, `backend_log_sources_read`, or `backend_db_connections_read` must be non-empty. `backend_response_statuses` and `backend_traces_collected` are optional but strongly recommended on the protocol-call path — same order as `backend_endpoints_called`. There is no automatic pass-criteria override on this cycle: if `status: pass` and the evidence is structurally valid, the gate honors it.
 
 For a multi-cycle pass (browser + backend, or browser + node + backend), every active cycle's evidence must be present — claiming `pass` without one cycle's fields will be overridden to fail.
 
@@ -53,22 +96,38 @@ Focus on the endpoints you changed — not every endpoint in the service.
 1. Run `git diff --name-only` and `git diff --name-only HEAD~1`
 2. **Ignore `.ironbee/`, `.claude/`, `.cursor/`** — tool config, not application code
 3. **Read the full diff** for route / handler / controller / service files in scope — note the wire-level address (HTTP method+path, gRPC service+method, GraphQL operation, WebSocket path), request shape, response shape, side effects (DB writes, downstream calls, queue puts)
-4. Before opening the request tool, you should be able to answer: what endpoints did I touch? What does each return on the happy path? What does each return on the error path? What side effects need verification?
+4. Before opening the request or log tools, you should be able to answer: what endpoints did I touch? What does each return on the happy path? What does each return on the error path? What side effects need verification? Which side (request or log) is easier to drive for this task?
 
 ### 2. Verify against the running service
+Pick the evidence path(s) that fit the task:
+
+**Protocol-call path** (you drive the request):
 - **Call each changed endpoint** with the matching tool — `mcp__backend-devtools__bedt_request_http` / `bedt_request_grpc` / `bedt_request_graphql` / `bedt_request_websocket-open`
 - **Cross-reference the response against the diff** — status, body shape, headers, gRPC status code
 - **Chain a follow-up call** to verify side effects (POST then GET, set then list, mutation then query, …)
 - **Test one error path** per new branch — invalid body, missing field, missing auth, 404 path
 - **Capture `traceId`** when available — useful for joining with downstream cycle evidence
 
+**Log-evidence path** (an external driver hits it; you read the logs):
+- **Register the service's log source** with `mcp__backend-devtools__bedt_log_register-source` (file / docker / kubernetes)
+- **Read or follow** with `bedt_log_read` / `bedt_log_read-multi` (point-in-time, filter by `pattern` / `level` / `since-until` / `jsonFilter`) or `bedt_log_follow` (streaming for after-the-trigger capture)
+- **Correlate with `traceId`** — use `pattern: "<traceId>"` to pull only the lines for one request
+- **Verify the expected line is present** AND **no unexpected ERROR-level entries appeared** for the touched route(s)
+
+**DB-evidence path** (you inspect database state directly):
+- **Open a named, readonly connection** with `mcp__backend-devtools__bedt_db_connect` — prefer `connectionStringEnv` so the secret never flows through the agent context.
+- **Discover schema** via `bedt_db_list-tables` + `bedt_db_describe-table` for migrations / column additions.
+- **Run targeted reads** via `bedt_db_query` for row-count, content, and constraint checks; `bedt_db_snapshot` + `bedt_db_diff` for pre/post state proofs; `bedt_db_watch-changes` + `bedt_db_get-changes` for streaming change capture during a triggered call.
+- **Disconnect** when done (`bedt_db_disconnect`) — optional; the session tears connections down at end.
+
 ---
 
 ## Full Mode (`/ironbee-verify full`, backend cycle)
 
-Exercise every endpoint reachable from files matching `backend.verifyPatterns`, not just the changed files. Do NOT run `git diff` or scope to recent changes.
+Exercise every endpoint / log source / DB table reachable from files matching `backend.verifyPatterns`, not just the changed files. Do NOT run `git diff` or scope to recent changes.
 
-- Hit every route / RPC method / GraphQL operation / WebSocket lifecycle in scope
+- Hit every route / RPC method / GraphQL operation / WebSocket lifecycle in scope (protocol-call) OR cover them via the log feed when an external driver / test suite drives them (log evidence) OR via direct DB inspection for schema / migration coverage (DB evidence)
 - Cover the success path AND at least one error path for each
 - Cover any auth-gated variant (unauthenticated, wrong role) where authentication is present
-- Any unexpected error response during the run is a fail, regardless of when it was introduced
+- For migrations: verify every affected table's schema (`bedt_db_describe-table`) + sample row count before / after
+- Any unexpected error response, unexpected ERROR-level log line, or unexpected schema drift during the run is a fail, regardless of when it was introduced

package/dist/clients/claude/platforms/command-verify.node.md

@@ -16,9 +16,9 @@ If the project has node backend verification enabled (`ironbee node enable` once
 2. **Connect**: `mcp__node-devtools__ndt_debug_connect` with one of `pid` / `processName` / `containerId` / `containerName` / `inspectorPort` / `wsUrl`. Inspector is auto-activated via SIGUSR1 if needed.
 3. **Pick an evidence path** for each changed code path:
    - **Probe path** (proves the code path executed): `mcp__node-devtools__ndt_debug_put-tracepoint` (or `put-logpoint` / `put-exceptionpoint`) at the changed code, exercise the path (e.g. trigger the API call from the browser), then `mcp__node-devtools__ndt_debug_get-probe-snapshots`. At least one probe must come back with `triggered: true`.
-   - **Log path** (proves no errors): exercise the path, then `mcp__node-devtools__ndt_debug_get-logs` with the error level filter. `backend_node_log_errors` must be empty for `status: pass`.
+   - **Log path** (proves no errors): exercise the path, then `mcp__node-devtools__ndt_debug_get-logs` with the error level filter. `node_log_errors` must be empty for `status: pass`.
 4. **Disconnect** (optional): `mcp__node-devtools__ndt_debug_disconnect`.
-5. **Submit verdict** including `backend_node_*` fields. If browser cycle is also active, include browser fields in the SAME verdict — do not submit two verdicts.
+5. **Submit verdict** including `node_*` fields. If browser cycle is also active, include browser fields in the SAME verdict — do not submit two verdicts.
 
 ### Verdict (node-cycle fields)
 ```json
@@ -26,12 +26,12 @@ If the project has node backend verification enabled (`ironbee node enable` once
   "session_id": "...",
   "status": "pass",
   "checks": ["POST /api/orders returned 201", "tracepoint at handler.ts:42 fired once"],
-  "backend_node_processes_connected": ["pid:12345 (next-server)"],
-  "backend_node_probes_set": [
+  "node_processes_connected": ["pid:12345 (next-server)"],
+  "node_probes_set": [
     { "type": "tracepoint", "location": "src/api/orders.ts:42", "triggered": true }
   ],
-  "backend_node_probe_snapshots_collected": 1,
-  "backend_node_log_errors": []
+  "node_probe_snapshots_collected": 1,
+  "node_log_errors": []
 }
 ```
 
@@ -54,7 +54,7 @@ Focus on the code you changed — not the entire Node service.
 - **Exercise the path end-to-end** (trigger from browser, curl, or the backend cycle if active)
 - **Each touched probe must report `triggered: true`** in `mcp__node-devtools__ndt_debug_get-probe-snapshots`
 - **Check one edge case per new branch** — invalid input, missing field, auth failure, …
-- **Logs** — `mcp__node-devtools__ndt_debug_get-logs` at error level; `backend_node_log_errors` must be empty for `pass`
+- **Logs** — `mcp__node-devtools__ndt_debug_get-logs` at error level; `node_log_errors` must be empty for `pass`
 
 ---
 
@@ -64,4 +64,4 @@ Probe every Node code path reachable from files matching `node.verifyPatterns`,
 
 - Place probes at every handler / route / service entry point in scope, plus key internal branch points (early returns, error catches, conditional middleware)
 - Exercise each path with at least one happy-path call AND one failure-path call
-- `backend_node_log_errors` must be empty after the full run — any unexpected log error is a fail, regardless of when it was introduced
+- `node_log_errors` must be empty after the full run — any unexpected log error is a fail, regardless of when it was introduced

package/dist/clients/claude/platforms/rule.backend.md

@@ -4,20 +4,29 @@
 
 ## Backend cycle (runtime-agnostic protocol verification)
 
-When the file matches `backend.verifyPatterns`, the Stop hook ALSO requires verification through the **backend-devtools** MCP server (prefix `bedt_`). Backend-cycle verification means making a real protocol call (HTTP / gRPC / GraphQL / WebSocket) against the running service and inspecting the response — language- and framework-independent.
+When the file matches `backend.verifyPatterns`, the Stop hook ALSO requires verification through the **backend-devtools** MCP server (prefix `bedt_`). The cycle is satisfied by **any one of three** evidence paths: a real protocol call (HTTP / gRPC / GraphQL / WebSocket) against the running service, log inspection from the running service (file / docker / kubernetes) when an external driver is hitting the endpoint, OR direct database inspection for schema / data-state changes. Pick whichever fits the task — language- and framework-independent in all three cases.
 
-The backend cycle and the node cycle are **independent**. Node attaches to a Node.js V8 inspector with non-blocking probes (`ndt_*`); backend drives wire protocols from outside (`bedt_*`). They can be active in the same task; both must be satisfied for `status: pass`.
+The backend cycle and the node cycle are **independent**. Node attaches to a Node.js V8 inspector with non-blocking probes (`ndt_*`); backend drives wire protocols and/or reads logs / DB state from outside (`bedt_*`). They can be active in the same task; both must be satisfied for `status: pass`.
 
 ### Backend-cycle additions to the main flow
 
 These attach to the **Required steps** above — they don't replace any step. Numbering follows the main flow:
 
-- **Within step 3 (run flow):** also run the backend flow: identify the affected endpoint(s) → call the matching protocol tool (`bedt_request_http` / `bedt_request_grpc` / `bedt_request_graphql` / `bedt_request_websocket-open` / `bedt_request_replay`) → inspect status / body / `traceId` → chain follow-up calls when verifying side effects. **A 4xx / 5xx response is a normal result, not an error** — only transport failures populate the `error` field.
-- **Within step 6 (submit verdict):** include `backend_endpoints_called` (the only required backend field), and optionally `backend_response_statuses` and `backend_traces_collected`. One verdict carries fields for every active cycle.
+- **Within step 3 (run flow):** also run the backend flow via ONE of three evidence paths:
+  - **Protocol-call** — identify the affected endpoint(s) → call the matching protocol tool (`bedt_request_http` / `bedt_request_grpc` / `bedt_request_graphql` / `bedt_request_websocket-open` / `bedt_request_replay`) → inspect status / body / `traceId` → chain follow-up calls when verifying side effects. **A 4xx / 5xx response is a normal result, not an error** — only transport failures populate the `error` field.
+  - **Log evidence** — `bedt_log_register-source` (file / docker / kubernetes) → `bedt_log_read` (point-in-time, supports `tail` / `since-until` / `pattern` / `level` / `parseJson` + `jsonFilter` / `contextBefore-After` / `select` / `coalesce`) OR `bedt_log_follow` + `bedt_log_get-followed` (streaming). Fit for jobs / queue workers / async handlers, or any case where an external driver is hitting the endpoint and you only need to verify what the server logged. `bedt_log_register-source` is mandatory on this path (the gate counts it as the setup step).
+  - **DB evidence** — `bedt_db_connect` (named, `connectionStringEnv` preferred, default readonly) → ONE of `bedt_db_query` / `bedt_db_describe-table` / `bedt_db_list-tables` / `bedt_db_snapshot` (+ optional `bedt_db_diff`) / `bedt_db_get-changes`. Fit for migrations, seed-data changes, query-result regressions, and any code change whose side effect lives in a relational DB. `bedt_db_connect` is mandatory on this path (same anti-fluke rule as `log-evidence` — the connection name is on the wire).
+- **Within step 6 (submit verdict):** include `backend_endpoints_called` for protocol-call evidence (optionally with `backend_response_statuses` and `backend_traces_collected`), `backend_log_sources_read` for log-evidence, and/or `backend_db_connections_read` for db-evidence. **At least one** of those three arrays must be non-empty. One verdict carries fields for every active cycle.
+
+### Trace correlation (`o11y_*` is auxiliary, not evidence)
+
+IronBee already injects the active verification `traceId` into every backend tool call via `_metadata.traceId`. That id outranks anything `bedt_o11y_new-trace-id` / `bedt_o11y_set-trace-context` would pin for the cycle, so the orchestrator's correlation root stays authoritative. The `o11y_*` tools are still useful for log searches (`bedt_log_read { pattern: traceId }` against an explicit id), but they don't count toward the gate.
 
 ### Additional BANNED for backend cycle
 
 - Calling `bedt_*` tools without first opening a verification cycle (`ironbee hook verification-start`).
 - Treating a 4xx / 5xx response as a transport failure when the test was specifically asking for that error condition (e.g. "POST should reject malformed body with 400"). Decide PASS/FAIL based on the test's intent, not the status code's HTTP-class default.
-- Submitting a backend-only verdict that omits `backend_endpoints_called` — any non-empty list of endpoints driven during verification is required.
-- Inferring backend behavior by reading code without making a real protocol call. The cycle is satisfied only by actually exercising the wire protocol.
+- Submitting a backend verdict that omits ALL of `backend_endpoints_called`, `backend_log_sources_read`, and `backend_db_connections_read` — at least one of those evidence arrays must be non-empty.
+- Inferring backend behavior by reading code without exercising any evidence path. The cycle is satisfied only by making a real protocol call, reading real logs, or inspecting real DB state on the running service.
+- Reading a pre-existing log source / DB unrelated to your task to fake the log-evidence or db-evidence path. `bedt_log_register-source` and `bedt_db_connect` are required setup steps on those paths so the registration / connection is on the wire.
+- Opening a DB connection with `allowWrites: true` to "set up" verification data without an explicit need (seed / migration). Read-only is the default for a reason — flipping it widens the blast radius if a query goes wrong.

package/dist/clients/claude/platforms/rule.node.md

@@ -19,11 +19,11 @@ Both cycles can be active simultaneously (e.g. you edit both a React component a
 These attach to the **Required steps** above — they don't replace any step. Numbering follows the main flow:
 
 - **Within step 3 (run flow):** also run the node flow: connect (`ndt_debug_connect`) → set probe (`ndt_debug_put-tracepoint` / `put-logpoint` / `put-exceptionpoint`) AND exercise + read snapshots (`ndt_debug_get-probe-snapshots`), OR exercise + read logs (`ndt_debug_get-logs`). When both browser and node cycles are active, run BOTH within the same verification cycle.
-- **Within step 6 (submit verdict):** include `backend_node_*` fields (`backend_node_processes_connected` non-empty, plus `backend_node_probes_set` and/or `backend_node_log_errors`). One verdict carries fields for every active cycle.
+- **Within step 6 (submit verdict):** include `node_*` fields (`node_processes_connected` non-empty, plus `node_probes_set` and/or `node_log_errors`). One verdict carries fields for every active cycle.
 
 ### Additional BANNED for node cycle
 
 - Calling `ndt_*` tools without first opening a verification cycle (`ironbee hook verification-start`).
 - **Calling `ndt_*` tools when the project's backend is NOT Node.js** (Java / Python / Go / Rust / .NET / Ruby / PHP / Elixir / etc.). Use the browser cycle only for non-Node backends.
-- Claiming `status: pass` for a node cycle when no probe triggered AND `backend_node_log_errors` was never collected.
-- Submitting a node-only verdict that omits `backend_node_processes_connected` — every node-cycle verdict requires this field non-empty.
+- Claiming `status: pass` for a node cycle when no probe triggered AND `node_log_errors` was never collected.
+- Submitting a node-only verdict that omits `node_processes_connected` — every node-cycle verdict requires this field non-empty.

package/dist/clients/claude/platforms/skill.backend.md

@@ -5,11 +5,15 @@
 
 ## Backend cycle — runtime- and language-agnostic
 
-The **backend protocol cycle** verifies backend changes by driving real protocol calls (HTTP / gRPC / GraphQL / WebSocket) against the running service and reading the responses. It works for ANY backend runtime: Node, Java, Python, Go, Rust, Ruby, .NET, PHP, Elixir, Kotlin, Scala — the agent never attaches to a process; it just calls endpoints.
+The **backend protocol cycle** verifies backend changes by driving real protocol calls (HTTP / gRPC / GraphQL / WebSocket) against the running service and reading the responses, OR by inspecting the logs of the running service (file / docker / kubernetes) when an external driver is hitting the endpoint. It works for ANY backend runtime: Node, Java, Python, Go, Rust, Ruby, .NET, PHP, Elixir, Kotlin, Scala — the agent never attaches to a process.
 
-**This is different from the node cycle.** Node-cycle (`ndt_*`) attaches to a V8 inspector and sets non-blocking probes inside a running Node.js process — it's Node-only. Backend-cycle (`bedt_*`) makes outside-in protocol calls against any service. They can be active at the same time when both are enabled.
+**This is different from the node cycle.** Node-cycle (`ndt_*`) attaches to a V8 inspector and sets non-blocking probes inside a running Node.js process — it's Node-only. Backend-cycle (`bedt_*`) makes outside-in protocol calls and/or reads logs of any service. They can be active at the same time when both are enabled.
 
-## Backend flow
+## Backend flow (three evidence paths — at least one is required)
+
+You can satisfy the cycle via **protocol-call evidence** (you drive the request yourself), **log evidence** (something else drives the request, you read the resulting logs), **DB evidence** (you inspect database state directly), or any combination. Pick whichever fits the task; one is enough.
+
+### Path A — Protocol-call evidence
 
 1. **Confirm a backend service is running** (the user's dev server, Docker compose, k8s port-forward, …). The agent itself does not start the service — ask the user if uncertain.
 2. **Identify the affected endpoint(s)** for your code change. Look at routes / handlers / controllers in the changed files. Map them to wire-level addresses (URL, gRPC service+method, GraphQL operation name, WebSocket path).
@@ -25,9 +29,44 @@ The **backend protocol cycle** verifies backend changes by driving real protocol
 4. **Inspect the response** — `status` (HTTP / gRPC code), body, headers, returned `traceId` (always W3C `traceparent`).
    **`4xx/5xx and gRPC non-OK are normal results, not errors.** A test for "404 Not Found" SHOULD return 404. Only transport-level failures (DNS, TLS, timeout, abort) populate the response's `error` field. Decide PASS/FAIL based on what your task actually requires.
 5. **Chain follow-up calls** if you need to verify side effects (e.g. POST then GET to confirm the new resource is readable). Use `bedt_request_set-default-headers` to pin auth tokens once per host, `bedt_request_set-cookies` for session cookies — both stay scoped to that target across calls.
-6. **Submit verdict** including `backend_*` fields. If browser and/or node cycles are also active, include their fields in the SAME verdict — do not submit two verdicts.
 
-### Backend verdict fields
+### Path B — Log evidence (when an external driver hits the endpoint)
+
+Useful when an integration test, the user, or a deploy script is already driving the protocol — your job is to verify "side B" by reading what the server logged. Also a fit for jobs / queue workers / cron handlers where there is no synchronous request to make.
+
+1. **Register the log source** with `mcp__backend-devtools__bedt_log_register-source` — pick `type: "file"` for any process whose stdout is redirected to a file, `type: "docker"` for a container (`container: "<name|id>"`), `type: "kubernetes"` for a pod (`pod`, optionally `kubernetesContainer` / `namespace`). Source names are session-unique; re-register to overwrite. Listing/check helpers: `bedt_log_list-sources`, `bedt_log_check-source`.
+2. **Read or follow the source**:
+   - `mcp__backend-devtools__bedt_log_read` / `bedt_log_read-multi` — point-in-time read across one or many sources. Filters: `tail` (last N lines), `since` / `until` (ISO-8601 — natively docker; file sources require `parseJson: true` so timestamp is extracted from a JSON field), `pattern` (substring; use for trace-id correlation), `level` (ERROR/WARN/INFO/DEBUG/TRACE/FATAL), `limit`, `parseJson`, `jsonFilter` (dot-path equality predicates against parsed JSON), `contextBefore` / `contextAfter`, `select` (dot-path projection to trim verbose JSONL), `coalesce` (fold multi-line stack traces into one line).
+   - `mcp__backend-devtools__bedt_log_follow` — open a streaming subscription that pushes lines into a ring buffer; `bedt_log_get-followed` drains it on demand; `bedt_log_stop-follow` tears it down. Use this when you need to capture logs that emit AFTER your trigger.
+3. **Verify the lines you got match the expectation** — error gone, expected log line present, trace-id chained through. Plain-text and JSON sources are both supported; JSON sources accept structural predicates (`jsonFilter: { 'level': 'error', 'route': '/api/orders' }`).
+4. **Unregister when done** — `bedt_log_unregister-source` cleans up. Optional; the session tears them down at end too.
+
+### Path C — DB evidence (when the change touches database state)
+
+Best fit for schema migrations, seed-data changes, query-result regressions, and any backend change whose side effect is visible in a relational DB. The agent opens a named, read-only-by-default connection and inspects the state — no need to drive a protocol call when the verification IS reading the DB.
+
+1. **Open a named connection** with `mcp__backend-devtools__bedt_db_connect` — `type: "postgres" | "mysql" | "sqlite"`, `connectionString` or (preferred) `connectionStringEnv`. Default is `allowWrites: false` (server-side READ ONLY mode); only set `allowWrites: true` if you need to seed test data. The session can hold multiple named connections side-by-side (`bedt_db_list-connections` to inspect).
+2. **Inspect state** — pick the tool that fits:
+   - `mcp__backend-devtools__bedt_db_list-tables` — discover tables.
+   - `mcp__backend-devtools__bedt_db_describe-table` — verify schema (columns / types / indexes / FKs) after a migration.
+   - `mcp__backend-devtools__bedt_db_query` — run an arbitrary read query (`SELECT count(*) FROM orders WHERE …`, etc.). Always parameterized — the gate honors readonly mode.
+   - `mcp__backend-devtools__bedt_db_snapshot` + `bedt_db_diff` — pre/post state diff for verifying that a code path changed exactly the rows it should.
+   - `mcp__backend-devtools__bedt_db_watch-changes` + `bedt_db_get-changes` — streaming change capture when a protocol call (or external driver) triggers writes you want to verify after the fact.
+3. **(Optional) Seed / migrate** — `bedt_db_seed` (structured) and `bedt_db_run-script` (raw SQL) write data; both require `allowWrites: true` at connect time. Use sparingly and prefer per-test transactions (`bedt_db_transaction-begin` / `-commit` / `-rollback`) so the seed doesn't leak across tests.
+4. **Disconnect when done** — `bedt_db_disconnect` releases the connection cleanly. Optional; the session tears them down at end too.
+
+### Trace correlation across paths (`o11y_*` primitives)
+
+The IronBee verification cycle already pins a W3C trace id on every backend tool call via `_metadata.traceId` (see `require-verification`). It outranks any trace pin the agent sets, so you usually don't need the `o11y_*` tools. They are still available when you want to grep logs by trace id, or anchor a multi-tool flow under an explicit id:
+
+- `mcp__backend-devtools__bedt_o11y_new-trace-id` — generate a fresh 32-hex id and pin it on the session (shadowed by IronBee's verification traceId for the cycle).
+- `mcp__backend-devtools__bedt_o11y_set-trace-context` — set / clear specific trace-context values.
+- `mcp__backend-devtools__bedt_o11y_get-trace-context` — inspect the current pin (useful for `bedt_log_read { pattern: "<traceId>" }`).
+
+### Submit verdict
+
+Include the fields matching the path(s) you exercised. If browser and/or node cycles are also active, include their fields in the SAME verdict — do not submit two verdicts.
+
 ```json
 {
   "session_id": "<sid>",
@@ -42,7 +81,29 @@ The **backend protocol cycle** verifies backend changes by driving real protocol
 }
 ```
 
-`backend_endpoints_called` is the only required field for the cycle (any non-empty array proves the agent engaged the protocol layer). `backend_response_statuses` and `backend_traces_collected` are optional but strongly recommended — same order as `backend_endpoints_called`. Status interpretation is YOUR call: there is no automatic pass-criteria override on this cycle. If the agent claims `status: pass` and the evidence is structurally valid, the gate honors it.
+Or, for a log-evidence path:
+
+```json
+{
+  "session_id": "<sid>",
+  "status": "pass",
+  "checks": ["api-server logged 'order 42 created' on POST /api/orders", "no ERROR-level lines after the change"],
+  "backend_log_sources_read": ["api-server"]
+}
+```
+
+Or, for a DB-evidence path:
+
+```json
+{
+  "session_id": "<sid>",
+  "status": "pass",
+  "checks": ["users table has new email_verified column with default false", "row count unchanged after migration"],
+  "backend_db_connections_read": ["app"]
+}
+```
+
+At least one of `backend_endpoints_called`, `backend_log_sources_read`, or `backend_db_connections_read` must be non-empty. The optional protocol-call fields (`backend_response_statuses`, `backend_traces_collected`) are strongly recommended when you used the protocol-call path — same order as `backend_endpoints_called`. Status interpretation is YOUR call: there is no automatic pass-criteria override on this cycle. If the agent claims `status: pass` and the evidence is structurally valid, the gate honors it.
 
 ## Multi-cycle (browser + backend, or browser + node + backend)
 

package/dist/clients/claude/platforms/skill.node.md

@@ -28,7 +28,7 @@ If you see `pom.xml`, `build.gradle`, `requirements.txt`, `pyproject.toml`, `go.
      - Read collected snapshots: `ndt_debug_get-probe-snapshots`. At least one probe must come back with `triggered: true`.
    - **Log path** (proves no errors during execution):
      - Exercise the path.
-     - Read errors: `ndt_debug_get-logs` with the error-level filter. `backend_node_log_errors` must be empty for `status: pass`.
+     - Read errors: `ndt_debug_get-logs` with the error-level filter. `node_log_errors` must be empty for `status: pass`.
 4. **Disconnect** (optional): `ndt_debug_disconnect`.
 
 ### Node verdict fields
@@ -37,18 +37,18 @@ If you see `pom.xml`, `build.gradle`, `requirements.txt`, `pyproject.toml`, `go.
   "session_id": "<sid>",
   "status": "pass",
   "checks": ["POST /api/orders returned 201", "tracepoint at handler.ts:42 fired once"],
-  "backend_node_processes_connected": ["pid:12345 (next-server)"],
-  "backend_node_probes_set": [
+  "node_processes_connected": ["pid:12345 (next-server)"],
+  "node_probes_set": [
     { "type": "tracepoint", "location": "src/api/orders.ts:42", "triggered": true }
   ],
-  "backend_node_probe_snapshots_collected": 1,
-  "backend_node_log_errors": []
+  "node_probe_snapshots_collected": 1,
+  "node_log_errors": []
 }
 ```
 
 For `status: "pass"` (node cycle):
 - If probes were set, at least one must have `triggered: true` (proves the code path executed).
-- If only logs were used, `backend_node_log_errors.length === 0` (no errors observed).
+- If only logs were used, `node_log_errors.length === 0` (no errors observed).
 - If both forms were used, both conditions must hold.
 
 ## Multi-cycle (browser + node simultaneously)
@@ -65,12 +65,12 @@ Submit ONE verdict carrying fields for every active cycle:
   "checks": ["checkout submits", "POST /api/orders returned 201", "no console errors"],
   "console_errors": 0,
   "network_failures": 0,
-  "backend_node_processes_connected": ["pid:12345 (next-server)"],
-  "backend_node_probes_set": [
+  "node_processes_connected": ["pid:12345 (next-server)"],
+  "node_probes_set": [
     { "type": "tracepoint", "location": "src/api/orders.ts:42", "triggered": true }
   ],
-  "backend_node_probe_snapshots_collected": 1,
-  "backend_node_log_errors": []
+  "node_probe_snapshots_collected": 1,
+  "node_log_errors": []
 }
 ```
 

package/dist/clients/cursor/hooks/require-verdict.js

@@ -44,7 +44,7 @@ async function run(projectDir) {
             permission: "deny",
             agent_message: `BLOCKED: You used verification tools (browser-devtools / node-devtools / backend-devtools) but did not submit a verdict. You MUST submit a verdict (pass or fail) before editing code.
 
-Submit your verdict first (include cycle-appropriate fields — browser fields for bdt_*, backend_node_* for ndt_*, backend_endpoints_called/backend_response_statuses for bedt_*):
+Submit your verdict first (include cycle-appropriate fields — browser fields for bdt_*, node_* for ndt_*, backend_endpoints_called/backend_response_statuses for bedt_*):
   echo '{"session_id":"${sessionId}","status":"fail","checks":[...],"issues":["describe what failed"], ...}' | ironbee hook submit-verdict
 
 Then you can edit code to fix the issues.`,