feat(observability): admin-only per-request timing detail via X-OS-Debug-Timing: json (#2408)

[os-zhuang]

What & why

Follow-up to #3163, completing the optional richer JSON diagnostic from #2408. The basic Server-Timing header tells you how many queries ran and their total time — but not which ones. This adds an admin-only per-query breakdown: an admin/service caller sends X-OS-Debug-Timing: json and gets back the slowest SQL statements (by shape) in a separate X-OS-Debug-Timing-Detail response header.

Crucially, the detail is admin-only even under global mode — an ordinary caller never sees SQL shapes, and even an admin only ever sees the parametrized statement (knex's ? placeholders), never the bindings, so no literal row value leaves the server.

How

• @objectstack/observability — PerfTiming gains opt-in per-event detail capture (enableDetail / recordDetail / details) plus the ambient recordServerTimingDetail. Detail is off by default (zero allocation on the hot path) and bounded by a cap. The disclosure gate gains a second level, privileged (set by allowPerfDisclosure, read via isPerfDisclosurePrivileged), so the richer detail is gated independently of the basic header.
• @objectstack/driver-sql — when detail capture is on, the knex query listener additionally records each query's parametrized statement + duration. Free when off (one boolean check).
• @objectstack/plugin-hono-server — X-OS-Debug-Timing: json enables detail capture; the middleware emits X-OS-Debug-Timing-Detail (the slowest queries, capped and sanitized to header-safe printable ASCII) only when the principal is a proven admin (gate.privileged).

Detail payload shape

{"db":{"count":6,"totalMs":210.3,"slowest":{"sql":"select * from widgets where id = ?","dur":88.1},"queries":[{"sql":"select * from widgets where id = ?","dur":88.1}, …]}}

Disclosure matrix

Request	Global off	Global on
no debug header	nothing	basic header
X-OS-Debug-Timing: 1, non-admin	nothing	basic header
X-OS-Debug-Timing: 1, admin	basic header	basic header
X-OS-Debug-Timing: json, non-admin	nothing	basic header, no detail
X-OS-Debug-Timing: json, admin	basic header + detail	basic header + detail

Tests / verification

• Unit: detail collector (capture/off/cap/categories), the privileged gate level, the driver's parametrized-SQL capture (asserts the literal binding never appears), and the middleware's json/basic/global paths incl. the "never leak detail under global mode" invariant.
• Real-HTTP end-to-end (server-timing.integration.test.ts): boots a real Hono server + real SQLite driver, and over a genuine socket confirms an admin sending X-OS-Debug-Timing: json gets the X-OS-Debug-Timing-Detail header with the actual query shapes, while a non-admin never does — even under global mode. This is the "does it work against a running server?" check that a browser dogfood would do, made deterministic.
• docs/OBSERVABILITY.md + a minor changeset updated.

All affected package builds (DTS typecheck) pass. Basic and global behavior are unchanged — json is purely additive.

Note on the open-core boundary

This is the last framework-side piece of #2408. The remaining item — surfacing this as a cloud console "perf panel" and defining the cloud's own "who is admin" policy — lives in the cloud repo (mechanism here, policy there), consistent with the existing observability split.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 18, 2026 6:17am

[github-actions]

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/observability, @objectstack/driver-sql, @objectstack/plugin-hono-server, @objectstack/runtime.

19 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/api/index.mdx (via @objectstack/runtime)
• content/docs/api/wire-format.mdx (via @objectstack/runtime)
• content/docs/automation/hook-bodies.mdx (via @objectstack/runtime)
• content/docs/concepts/north-star.mdx (via packages/runtime)
• content/docs/data-modeling/drivers.mdx (via @objectstack/driver-sql, @objectstack/runtime)
• content/docs/deployment/index.mdx (via @objectstack/runtime)
• content/docs/deployment/production-readiness.mdx (via @objectstack/runtime)
• content/docs/deployment/single-project-mode.mdx (via @objectstack/runtime)
• content/docs/deployment/vercel.mdx (via @objectstack/runtime)
• content/docs/getting-started/glossary.mdx (via @objectstack/driver-sql)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/plugin-hono-server, @objectstack/runtime)
• content/docs/permissions/authentication.mdx (via @objectstack/plugin-hono-server, @objectstack/runtime)
• content/docs/plugins/anatomy.mdx (via @objectstack/driver-sql)
• content/docs/plugins/index.mdx (via @objectstack/plugin-hono-server)
• content/docs/plugins/packages.mdx (via @objectstack/driver-sql, @objectstack/plugin-hono-server, @objectstack/runtime)
• content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/index.mdx (via @objectstack/driver-sql, @objectstack/runtime)
• content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/driver-sql, @objectstack/runtime)
• content/docs/releases/implementation-status.mdx (via @objectstack/observability, @objectstack/driver-sql, @objectstack/plugin-hono-server, @objectstack/runtime)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.