feat(tracing): Span.startChild + getActiveSpan + honoTracing helper

[stackbilt-admin]

Summary

Three dogfood-driven ergonomics lifts surfaced while instrumenting `tarotscript-worker` (tarotscript#163).

1. `Span.startChild(name, attrs?)` — convenience method that saves ~3 lines of plumbing per child span (ergonomics: Span.startChild() + Hono-aware middleware helper #3)
2. `getActiveSpan()` + `Tracer.runWithSpan()` — AsyncLocalStorage-backed active span so deep code creates child spans without threading parent context through function signatures (feat: AsyncLocalStorage-backed active span context #4)
3. `honoTracing()` middleware — batteries-included helper that wraps the full root-span lifecycle every dogfood worker was hand-rewriting (ergonomics: Span.startChild() + Hono-aware middleware helper #3)

Why it matters

Every Stackbilt worker instrumented with this library (stackbilt-web, edge-auth, tarotscript, img-forge, aegis, pro-tier customer workers) was rewriting the same ~30-line middleware. Centralizing it means bug fixes propagate automatically, new workers integrate in 2 lines instead of 30, and deep code (interpreters, LLM providers, scaffold materializers) can now participate in tracing without taking a hard dep on observability.

AsyncLocalStorage notes

Requires `nodejs_als` or `nodejs_compat` compat flag in `wrangler.toml`. When unavailable, `getActiveSpan()` returns `undefined` and `runWithSpan` becomes an identity wrapper — no crashes, just no-op.

honoTracing features

• Wraps `next()` in `tracer.runWithSpan(rootSpan, ...)` for automatic active-span scoping
• Records `http.*` attributes, `recordError()` on throw, `setStatus('error')` on 5xx
• Publishes root span to `c.get('rootSpan')` (or custom `contextKey`)
• Uses `ctx.waitUntil(Promise.allSettled([tracer.flush(), metrics.flush()]))` so ingest doesn't block the response
• Options: `skip`, `attributes`, `spanNamer`, `contextKey`
• Accepts minimal `HonoTracingMonitoring` shape — decoupled from full `createMonitoring` surface

Test plan

• typecheck clean
• 82/82 tests pass (71 existing redact + 11 new ergonomics)
• startChild trace-id inheritance, parent linkage, attributes
• runWithSpan/getActiveSpan sync, async, deep-stack scenarios
• honoTracing: null-safety, skip, root span publication, active-span scoping, 5xx → error, thrown error → recordError, custom spanNamer + attributes
• Deploy to tarotscript-worker dogfood, verify child spans appear in dashboards without threading
• Follow-up: docs+release: publish to npm + ship Quickstart for Hono workers #5 (npm publish + Hono quickstart docs) — deferred until dogfooded in prod

Depends on

Independent of #7 (span-drops fix in #8) — they touch different methods, can land in either order.

Closes #3
Closes #4

🤖 Generated with Claude Code