feat(core): bounded query debug trace (#992)

[shaun0927]

Progress / Review status

Auto-refreshed 2026-05-13 — owner comments cleaned up to reduce review noise.

Field	Value
Branch	feat/992-query-debug → feat/986-agentql-query-dsl
Draft	no
CI	—
Mergeable	✅ MERGEABLE
Review decision	—
Codex (latest)	—
Other reviewers (latest)	—
Head	b565579 — Make extraction failures inspectable without bloating responses
Commits	1

_{Owner comment cleanup: 0 issue + 0 inline review comments deleted. Outstanding feedback from automated/external reviewers above is unchanged.}

---

Summary

• adds bounded in-memory query debug store with text caps and token/password-style redaction
• registers oc_query_debug for latest { tabId, kind } debug retrieval
• instruments extract_data query/schema paths for found/missing fields, strategies, duration, output size, and parser/schema failures

Repo-fit / duplicate check

• Checked open PRs for feat(core): bounded query debug trace for extraction and element matching #992/query-debug; no existing PR covers this issue.
• Stacked on feat(extraction): local query DSL for extract_data (#986) #1099 because this PR observes the local query DSL added there.
• Scope remains lightweight/local: no full DOM/HTML, no AgentQL/Playwright/cloud debugger dependency, and normal extract_data responses stay compact.

Tests

• npx jest tests/query-debug/store.test.ts tests/tools/oc-query-debug.test.ts tests/tools/extract-data.test.ts --runInBand
• npm run build
• npm run lint:changed

Merge-time real OpenChrome verification

1. Start OpenChrome and navigate to a fixture with partial structured data.
2. Run extract_data with a query containing one existing and one missing field.
3. Call oc_query_debug({ tabId, kind: "extract" }).
4. Verify payload includes normalized query, parsed field summary, strategies, found/missing fields, duration, output size, and no full DOM/HTML.
5. Repeat with malformed query and verify notes[0] reports parser failure.
6. Run a fixture containing password/token-like text and verify debug JSON redacts those values.

Closes #992

[shaun0927]

Merge rationale (stack consolidation)

Intent. Closes #992 — adds a bounded in-memory query debug store, registers oc_query_debug for retrieving the latest { tabId, kind } debug entry, and instruments extract_data query/schema paths (found/missing fields, strategies, duration, output size, parser/schema failures).

Why this is correct.

• Bounded store with text caps and token/password-style redaction — debug data cannot grow unbounded or leak credentials.
• Adds an opt-in retrieval tool (oc_query_debug) without changing extract_data's response shape.
• Stacked on feat(extraction): local query DSL for extract_data (#986) #1099 (local query DSL) since this PR observes its events; feat(core): bounded query debug trace (#992) #1115 only reads from the DSL, so merge order vs feat(extraction): local query DSL for extract_data (#986) #1099 is not load-bearing for correctness.
• Scope contained: 7 files, +299/-4. No Codex P0/P1/P2 outstanding.

CI. Targets the AgentQL query DSL feature branch; workflow runs only on main/develop PRs, so this PR has no CI of its own. CI will run on the chain root when consolidated to develop.