feat: OpenTelemetry instrumentation (closes #34)

[SokratisVidros]

Summary

Adds a first-party otelPlugin that emits OpenTelemetry spans for workflow and step execution. @opentelemetry/api is an optional peer dependency — users who don't import the plugin pay zero runtime cost.

• One pg_workflows.workflow.run span per worker execution, with child spans per step kind (step.run, step.waitFor, step.delay, step.waitUntil, step.pause, step.poll, step.invokeChildWorkflow, step.sleep aliased to delay).
• Cache-hit suppression: steps replayed from the timeline after a pause emit no span (with the step.poll exception called out below).
• Error path: failures get recordException + ERROR status; the original error is re-thrown so engine retry/DLQ behaviour is unchanged.
• New optional wrap?(context, next) hook on WorkflowPlugin lets any plugin compose middleware around the workflow handler — the engine builds the chain in registration order.
• WorkflowContext gains resourceId (optional) and attempt (required) so plugins can read them without a DB round-trip.

Design and plan

• Spec: docs/superpowers/specs/2026-05-21-otel-instrumentation-design.md
• Plan: docs/superpowers/plans/2026-05-21-otel-instrumentation.md

Out of scope for v1 (explicitly deferred)

• Metrics (counters / histograms / queue depth)
• Trace context propagation across child workflows and from external HTTP callers (both need durable storage; deferred together)
• DLQ-only failure spans
• step.poll cache-hit suppression — every poll execution emits a span (the test-helper fastForwardWorkflow pre-writes output, so a naive cache-hit guard would suppress legitimate spans). Trade-off documented in the design doc.

Test Plan

• npm run test:unit — 138 passed, 1 skipped, 1 todo (16 new OTel tests across happy paths, error paths, cache-hit replay, span duration, plugin composition, and the isCachedHit predicate)
• npm run build — clean
• npm run lint — clean
• Manual smoke: import otelPlugin, register a NodeSDK, run a workflow with a step.run + step.waitFor + step.invokeChildWorkflow, inspect traces in your collector of choice
• Verify zero runtime cost when otelPlugin is not imported (no @opentelemetry/api resolution required)

🤖 Generated with Claude Code