suaveplan/openspec/archive/2026-04-29-timing-spec-conformance/proposal.md

OpenSpec Change: timing-spec-conformance

• Change ID: timing-spec-conformance
• Package: @suaveplan/timing
• Status: PROPOSED
• Date: 2026-04-26

Summary

Add **Verified by:** lines to every requirement in openspec/specs/timing/spec.md, fix two real implementation drifts inline, and add a consolidated src/timing.spec-conformance.test.ts so that bun scripts/openspec-conformance.ts @suaveplan/timing exits 0. No public surface trimming.

Current state

@suaveplan/timing has 12 requirements (TM-01 through TM-12) and 137 passing tests across stopwatch, scheduler, throttle/debounce, decay, timer/countdown, vector-clock, errors, and OTel modules. Two real drifts surfaced during the audit:

1. TM-11 incomplete OTel emission. The spec required "stopwatch elapsed, scheduler queue depth, and timer tick counter" to emit. Only standalone helpers recordStopwatchElapsed and incrementTimerTick existed; they were never called by stopwatch, scheduler, or timer modules, and recordSchedulerQueueDepth did not exist at all.
2. No **Verified by:** lines on any of the 12 requirements.

Plus the audit-level finding that openspec/archive/2026-04-19-enterprise-timing/tasks.md carries the historical phrase retroactively ticked; opening this change folder lifts that block.

What changes

1. Add recordSchedulerQueueDepth to src/otel/timing-otel.ts (lazy ObservableGauge with mutable observed value, no-op without exporter). Re-export from src/index.ts.
2. Wire scheduler.schedule, the per-task finally, handle-cancel, top-level cancel, and dispose to call recordSchedulerQueueDepth(_tasks.size) so queue-depth telemetry tracks the live task map.
3. Wire stopwatch.stop to call recordStopwatchElapsed(_accumulated).
4. Wire createTimer.start to invoke incrementTimerTick() on each interval before the user's onTick.
5. Add src/timing.spec-conformance.test.ts covering: throttle window count, debounce flush/cancel/maxWait, vector-clock relation matrix + JSON round-trip + update max-merge, scheduler drain order + pre-abort, countdown pause/resume invariant with injected clock, stopwatch monotonicity across laps, and OTel no-op smoke for the new gauge plus the existing helpers.
6. Add **Verified by:** lines under every requirement in openspec/specs/timing/spec.md.

Impact

• Public API gains one new export: recordSchedulerQueueDepth. No removals, no renames.
• Stopwatch .stop(), scheduler enqueue/dequeue, and timer ticks now emit OTel telemetry (no-op without exporter, so observable behaviour for existing consumers is unchanged).
• One new test file (~200 lines).
• openspec/specs/timing/spec.md gains 12 **Verified by:** lines.