36 lines
2.7 KiB
Markdown
36 lines
2.7 KiB
Markdown
# 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.
|