@handsforbots/semantic-event-observability 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/LICENSE.md +9 -0
  2. package/README.md +141 -2
  3. package/adapters/genericEventBus.js +20 -0
  4. package/adapters/instrumentChannel.js +22 -0
  5. package/core/CorrelationContext.js +49 -0
  6. package/core/EventBuffer.js +37 -0
  7. package/core/MetricsRegistry.js +200 -0
  8. package/core/PhaseTracker.js +143 -0
  9. package/core/Policy.js +87 -0
  10. package/core/SessionTracker.js +23 -0
  11. package/core/TraceContextBridge.js +74 -0
  12. package/core/TraceMapper.js +167 -0
  13. package/core/TurnMetricsCollector.js +19 -0
  14. package/core/TurnModel.js +87 -0
  15. package/core/baggage.d.ts +12 -0
  16. package/core/baggage.js +68 -0
  17. package/core/bucketEventName.js +11 -0
  18. package/core/createObservability.js +611 -0
  19. package/core/definePhaseModel.js +14 -0
  20. package/core/eventInstrumentation.js +21 -0
  21. package/core/isErrorEvent.js +9 -0
  22. package/core/telemetryAttributes.js +44 -0
  23. package/core/turnSpanNaming.js +73 -0
  24. package/docs/architecture.md +106 -0
  25. package/docs/custom-exporter.md +135 -0
  26. package/docs/exporters.md +180 -0
  27. package/docs/getting-started.md +192 -0
  28. package/docs/grafana-validation.md +71 -0
  29. package/docs/handsforbots-adapter.md +64 -0
  30. package/docs/handsforbots-roadmap.md +193 -0
  31. package/docs/metrics-roadmap.md +145 -0
  32. package/docs/publishing.md +55 -0
  33. package/docs/renaming.md +65 -0
  34. package/docs/roadmap.md +467 -0
  35. package/docs/tail-sampling.md +99 -0
  36. package/exporters/console.js +29 -0
  37. package/exporters/devPanel.js +204 -0
  38. package/exporters/faro.js +71 -0
  39. package/exporters/index.js +58 -0
  40. package/exporters/langfuse.js +161 -0
  41. package/exporters/langsmith.js +168 -0
  42. package/exporters/llmExporterState.js +84 -0
  43. package/exporters/memory.js +18 -0
  44. package/exporters/otel.js +236 -0
  45. package/exporters/otelTraceBackend.js +51 -0
  46. package/exporters/webVitals.js +73 -0
  47. package/grafana/semantic-event-observability.json +250 -0
  48. package/grafana/semantic-event-observability.lgtm.json +399 -0
  49. package/index.d.ts +312 -0
  50. package/index.js +31 -0
  51. package/package.json +83 -3
  52. package/packageIdentity.js +41 -0
  53. package/utils/id.js +10 -0
  54. package/utils/probeOptional.js +42 -0
  55. package/utils/safeJson.js +74 -0
package/LICENSE.md ADDED
@@ -0,0 +1,9 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright © 2024 Alex Lana and Hands for Bots contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6
+
7
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8
+
9
+ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,142 @@
1
- # Temporary Holding Version
1
+ # Semantic Event Observability
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Semantic observability for async event systems: logs, metrics, and tracing with **optional** exporters.
4
+
5
+ Built to sit on top of proven stacks (OpenTelemetry, Grafana Faro, Langfuse, LangSmith). If an exporter dependency is missing, the host application keeps working — telemetry is simply skipped for that backend.
6
+
7
+ **Scope:** semantic flow observability (turns, phases, queue pressure, telemetry health) — **not** service uptime, `/health` endpoints, or K8s probes. See [architecture — scope](./docs/architecture.md#scope).
8
+
9
+ > **Working title.** The npm name lives in `packageIdentity.js`. Change `PACKAGE_SLUG` there when the final product name is decided.
10
+
11
+ ## Quick start (Hands for Bots)
12
+
13
+ Add the **Observability** output plugin:
14
+
15
+ ```javascript
16
+ bot_settings.plugins.push({
17
+ type: 'output',
18
+ plugin: 'Observability',
19
+ environment: 'development',
20
+ exporters: ['memory', 'devPanel'],
21
+ })
22
+ ```
23
+
24
+ Enable the dev panel:
25
+
26
+ ```javascript
27
+ localStorage.setItem('semantic-event-observability:debug', 'true')
28
+ location.reload()
29
+ ```
30
+
31
+ **−** collapses the panel to its title bar. That choice stays in `localStorage` (`semantic-event-observability:panel`). **×** turns the panel off.
32
+
33
+ Configure exporters and policy via plugin options:
34
+
35
+ ```javascript
36
+ {
37
+ type: 'output',
38
+ plugin: 'Observability',
39
+ environment: 'production',
40
+ sampleRate: 0.2,
41
+ maxEventsPerMinute: 120,
42
+ exporters: ['memory', 'devPanel', 'faro', 'otel', 'langfuse', 'langsmith'],
43
+ exporterConfig: {
44
+ faro: { /* optional injected client */ },
45
+ otel: { /* api: injected OpenTelemetry API */ },
46
+ langfuse: { project: 'my-app' },
47
+ langsmith: { projectName: 'my-app' },
48
+ },
49
+ }
50
+ ```
51
+
52
+ ## Generic event bus
53
+
54
+ ```javascript
55
+ import { createObservability, instrumentEventBus } from './index.js'
56
+
57
+ const observability = createObservability({
58
+ turnStartEvents: ['user.message'],
59
+ turnEndEvents: ['bot.response'],
60
+ exporters: ['memory', 'console', 'otel'],
61
+ })
62
+
63
+ instrumentEventBus(observability, myBus, {
64
+ stateProvider: () => ({ queueDepth: myQueue.length }),
65
+ })
66
+ ```
67
+
68
+ ## Exporters
69
+
70
+ | ID | Dependency | Destination |
71
+ |----|------------|-------------|
72
+ | `memory` | none | Ring buffer / debug export |
73
+ | `console` | none | Browser console |
74
+ | `devPanel` | none | Floating debug panel |
75
+ | `otel` | `@opentelemetry/api` (optional) | Tempo / Mimir via OTel collector |
76
+ | `faro` | `@grafana/faro-web-sdk` (optional) | Loki via Faro collector |
77
+ | `langfuse` | `@langfuse/tracing` (optional) | Langfuse traces |
78
+ | `langsmith` | `langsmith` (optional) | LangSmith runs |
79
+ | `webVitals` | `web-vitals` (optional) | Core Web Vitals → `sevo_web_vital` |
80
+
81
+ Dependencies are **optional peer dependencies**. Inject clients manually when dynamic import is not available:
82
+
83
+ ```javascript
84
+ exporterConfig: {
85
+ faro: { client: window.faro },
86
+ otel: { api: traceApi },
87
+ langfuse: { startObservation },
88
+ langsmith: { RunTree },
89
+ }
90
+ ```
91
+
92
+ ## Attributes, baggage and counters
93
+
94
+ ```javascript
95
+ observability.setAttributes({ 'greeting.kind': 'directed', 'greeting.index': 3 })
96
+ observability.getTraceHeaders()
97
+ // { traceparent: '00-…', baggage: 'greeting.kind=directed,greeting.index=3' }
98
+ observability.recordCounter('h4b_experiment_exposed_total', 1, { experiment: 'greeting', 'greeting.kind': 'directed' })
99
+ ```
100
+
101
+ - **`setAttributes(attributes)` / `getAttributes()`.** Replaces the attributes (strings, finite numbers, booleans) put on every event (`event.attributes`) and every span: turn root, phases and events. Keep them to codes, never user text.
102
+ - **`baggage` header.** `getTraceHeaders()` adds the attributes as a [W3C Baggage](https://www.w3.org/TR/baggage/) header. If an injected carrier already has a `baggage` header, the two are merged and the attributes win on the same key. Nothing is added when `enabled: false`.
103
+ - **`recordCounter(name, value = 1, labels)`.** A counter that is never sampled nor rate-limited. The `otel` exporter creates the OpenTelemetry Counter on first use and keeps the labels as given (no `sevo.` prefix).
104
+ - **Baggage helpers.** `encodeBaggage`, `parseBaggage` and `mergeBaggage` come from the main entry and from `@handsforbots/semantic-event-observability/baggage`, which has no other imports and suits a server.
105
+
106
+ ## Security defaults
107
+
108
+ - Payload redaction via denylist (`password`, `token`, `history`, …)
109
+ - Payload truncation (`maxPayloadBytes`, default 2 KB)
110
+ - Per-minute rate limit (`maxEventsPerMinute`, default 120)
111
+ - Sampling (`sampleRate`, default 1 in dev — lower in production)
112
+ - Turn events are never sampled out
113
+
114
+ Defense in depth: also rate-limit at the collector before Loki/Tempo.
115
+
116
+ ## Grafana
117
+
118
+ | File | Use |
119
+ |------|-----|
120
+ | `grafana/semantic-event-observability.json` | Import template (select Loki/Tempo/Prometheus datasources) |
121
+ | `grafana/semantic-event-observability.lgtm.json` | Pre-provisioned in [`examples/`](../../examples/) via `docker-compose.observability.yml` |
122
+
123
+ The example stack mounts the `.lgtm.json` variant into `grafana/otel-lgtm` and sets it as the home dashboard.
124
+
125
+ ## Documentation
126
+
127
+ - [Getting started](./docs/getting-started.md)
128
+ - [Architecture](./docs/architecture.md)
129
+ - [Library roadmap & abstractions](./docs/roadmap.md)
130
+ - [Metrics checklist (`sevo_*`)](./docs/metrics-roadmap.md)
131
+ - [Exporters](./docs/exporters.md)
132
+ - [Tail sampling guidance](./docs/tail-sampling.md)
133
+ - [Grafana dashboard validation](./docs/grafana-validation.md)
134
+ - [Custom exporter cookbook](./docs/custom-exporter.md)
135
+ - [Publishing to npm](./docs/publishing.md)
136
+ - [Hands for Bots adapter](./docs/handsforbots-adapter.md)
137
+ - [Hands for Bots roadmap (`hfb_*`)](./docs/handsforbots-roadmap.md)
138
+ - [Renaming the package](./docs/renaming.md)
139
+
140
+ ## Future npm publish
141
+
142
+ See [publishing.md](./docs/publishing.md). TypeScript types ship in `index.d.ts`.
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Generic adapter for event buses exposing on() and trigger().
3
+ */
4
+ export function instrumentEventBus(observability, bus, options = {}) {
5
+ return observability.instrument(bus, options)
6
+ }
7
+
8
+ /**
9
+ * Convenience helper to bootstrap observability + bus instrumentation in one call.
10
+ */
11
+ export function createInstrumentedBus(bus, options = {}) {
12
+ const { createObservability } = options
13
+ if (typeof createObservability !== 'function') {
14
+ throw new Error('createInstrumentedBus requires createObservability in options')
15
+ }
16
+
17
+ const observability = createObservability(options.observability || {})
18
+ observability.instrument(bus, options.instrument || {})
19
+ return { observability, bus }
20
+ }
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Instrument BroadcastChannel, MessagePort, or similar postMessage APIs.
3
+ */
4
+ export function instrumentChannel(observability, channel, options = {}) {
5
+ if (!channel || typeof channel.postMessage !== 'function') {
6
+ throw new Error('instrumentChannel expects an object with postMessage()')
7
+ }
8
+
9
+ const eventName = options.eventName || 'channel.post'
10
+ const recordType = options.type || 'custom'
11
+
12
+ const originalPostMessage = channel.postMessage.bind(channel)
13
+ channel.postMessage = function instrumentedPostMessage(data, transfer) {
14
+ observability.record(eventName, data, { type: recordType })
15
+ if (transfer !== undefined) {
16
+ return originalPostMessage(data, transfer)
17
+ }
18
+ return originalPostMessage(data)
19
+ }
20
+
21
+ return channel
22
+ }
@@ -0,0 +1,49 @@
1
+ import { createId } from '../utils/id.js'
2
+ import TurnModel, { defineTurnModel } from './TurnModel.js'
3
+
4
+ /**
5
+ * Tracks turn/session correlation for async event flows.
6
+ */
7
+ export default class CorrelationContext {
8
+ constructor(options = {}) {
9
+ this.sessionId = options.sessionId || createId('session')
10
+ this.turnModel = new TurnModel(
11
+ options.turnModel || defineTurnModel({
12
+ startEvents: options.turnStartEvents,
13
+ endEvents: options.turnEndEvents,
14
+ }),
15
+ )
16
+ this.turnMetadata = {}
17
+ }
18
+
19
+ startSession(sessionId = createId('session')) {
20
+ this.sessionId = sessionId
21
+ this.turnModel = new TurnModel({
22
+ startEvents: [...this.turnModel.startEvents],
23
+ endEvents: [...this.turnModel.endEvents],
24
+ })
25
+ this.turnMetadata = {}
26
+ }
27
+
28
+ observeBusEvent(eventName) {
29
+ return this.turnModel.observeBusEvent(eventName)
30
+ }
31
+
32
+ getContext() {
33
+ return {
34
+ sessionId: this.sessionId,
35
+ ...this.turnModel.getContext(),
36
+ turnMetadata: { ...this.turnMetadata },
37
+ }
38
+ }
39
+
40
+ setTurnMetadata(metadata = {}) {
41
+ this.turnMetadata = { ...this.turnMetadata, ...metadata }
42
+ }
43
+
44
+ getActiveTurnAge() {
45
+ return this.turnModel.getActiveTurnAge()
46
+ }
47
+ }
48
+
49
+ export { defineTurnModel }
@@ -0,0 +1,37 @@
1
+ /**
2
+ * In-memory ring buffer for dev panel and debug export.
3
+ */
4
+ export default class EventBuffer {
5
+ constructor(maxSize = 200) {
6
+ this.maxSize = maxSize
7
+ this.events = []
8
+ this.metrics = []
9
+ }
10
+
11
+ push(event) {
12
+ this.events.push(event)
13
+ if (this.events.length > this.maxSize) {
14
+ this.events.shift()
15
+ }
16
+ }
17
+
18
+ pushMetric(metric) {
19
+ this.metrics.push(metric)
20
+ if (this.metrics.length > this.maxSize) {
21
+ this.metrics.shift()
22
+ }
23
+ }
24
+
25
+ getTimeline(limit = this.maxSize) {
26
+ return this.events.slice(-limit)
27
+ }
28
+
29
+ getMetrics(limit = this.maxSize) {
30
+ return this.metrics.slice(-limit)
31
+ }
32
+
33
+ clear() {
34
+ this.events = []
35
+ this.metrics = []
36
+ }
37
+ }
@@ -0,0 +1,200 @@
1
+ export const SEVO_METRICS = {
2
+ TURN_DURATION: 'sevo_turn_duration_ms',
3
+ PHASE_DURATION: 'sevo_phase_duration_ms',
4
+ PHASE_WAIT: 'sevo_phase_wait_ms',
5
+ TURNS_TOTAL: 'sevo_turns_total',
6
+ EVENTS_DROPPED: 'sevo_events_dropped_total',
7
+ STATE_GAUGE: 'sevo_state_gauge',
8
+ EVENTS_EMITTED: 'sevo_events_emitted_total',
9
+ EXPORTER_ERRORS: 'sevo_exporter_errors_total',
10
+ ACTIVE_TURNS: 'sevo_active_turns',
11
+ SESSION_TURNS_TOTAL: 'sevo_session_turns_total',
12
+ WEB_VITAL: 'sevo_web_vital',
13
+ BUS_EVENTS_TOTAL: 'sevo_bus_events_total',
14
+ CUSTOM_METRICS_TOTAL: 'sevo_custom_metrics_total',
15
+ LISTENER_DURATION: 'sevo_listener_duration_ms',
16
+ }
17
+
18
+ /** @deprecated Use SEVO_METRICS */
19
+ export const SEO_METRICS = SEVO_METRICS
20
+
21
+ /**
22
+ * Canonical sevo_* metric recording for Semantic Event Observability.
23
+ */
24
+ export function createMetricsRegistry(options = {}) {
25
+ const environment = options.environment || 'development'
26
+ const listeners = new Set()
27
+
28
+ function emit(metric) {
29
+ const record = {
30
+ name: metric.name,
31
+ type: metric.type,
32
+ value: metric.value,
33
+ labels: {
34
+ environment,
35
+ ...(metric.labels || {}),
36
+ },
37
+ timestamp: new Date().toISOString(),
38
+ }
39
+
40
+ for (const listener of listeners) {
41
+ try { listener(record) } catch { /* noop */ }
42
+ }
43
+
44
+ return record
45
+ }
46
+
47
+ return {
48
+ SEVO_METRICS,
49
+
50
+ subscribe(listener) {
51
+ listeners.add(listener)
52
+ return () => listeners.delete(listener)
53
+ },
54
+
55
+ recordTurnDuration(durationMs, labels = {}) {
56
+ if (durationMs == null || Number.isNaN(durationMs)) return
57
+ return emit({
58
+ name: SEVO_METRICS.TURN_DURATION,
59
+ type: 'histogram',
60
+ value: Math.max(0, durationMs),
61
+ labels,
62
+ })
63
+ },
64
+
65
+ recordPhaseDuration(phase, durationMs, labels = {}) {
66
+ if (durationMs == null || Number.isNaN(durationMs)) return
67
+ return emit({
68
+ name: SEVO_METRICS.PHASE_DURATION,
69
+ type: 'histogram',
70
+ value: Math.max(0, durationMs),
71
+ labels: { phase, ...labels },
72
+ })
73
+ },
74
+
75
+ recordPhaseWait(phase, waitMs, labels = {}) {
76
+ if (waitMs == null || Number.isNaN(waitMs)) return
77
+ return emit({
78
+ name: SEVO_METRICS.PHASE_WAIT,
79
+ type: 'histogram',
80
+ value: Math.max(0, waitMs),
81
+ labels: { phase, ...labels },
82
+ })
83
+ },
84
+
85
+ recordTurnStatus(status, labels = {}) {
86
+ return emit({
87
+ name: SEVO_METRICS.TURNS_TOTAL,
88
+ type: 'counter',
89
+ value: 1,
90
+ labels: { status, ...labels },
91
+ })
92
+ },
93
+
94
+ recordEventDropped(reason) {
95
+ return emit({
96
+ name: SEVO_METRICS.EVENTS_DROPPED,
97
+ type: 'counter',
98
+ value: 1,
99
+ labels: { reason: reason || 'unknown' },
100
+ })
101
+ },
102
+
103
+ recordStateGauge(key, value, labels = {}) {
104
+ if (typeof value !== 'number' || Number.isNaN(value)) return
105
+ return emit({
106
+ name: SEVO_METRICS.STATE_GAUGE,
107
+ type: 'gauge',
108
+ value,
109
+ labels: { key, ...labels },
110
+ })
111
+ },
112
+
113
+ recordEventEmitted(eventType, labels = {}) {
114
+ return emit({
115
+ name: SEVO_METRICS.EVENTS_EMITTED,
116
+ type: 'counter',
117
+ value: 1,
118
+ labels: { event_type: eventType || 'unknown', ...labels },
119
+ })
120
+ },
121
+
122
+ recordExporterError(exporterId) {
123
+ return emit({
124
+ name: SEVO_METRICS.EXPORTER_ERRORS,
125
+ type: 'counter',
126
+ value: 1,
127
+ labels: { exporter: exporterId || 'unknown' },
128
+ })
129
+ },
130
+
131
+ recordActiveTurns(count) {
132
+ if (typeof count !== 'number' || Number.isNaN(count)) return
133
+ return emit({
134
+ name: SEVO_METRICS.ACTIVE_TURNS,
135
+ type: 'gauge',
136
+ value: Math.max(0, count),
137
+ labels: {},
138
+ })
139
+ },
140
+
141
+ recordSessionTurnsRollup(counts = {}, labels = {}) {
142
+ const records = []
143
+ if (counts.completed > 0) {
144
+ records.push(emit({
145
+ name: SEVO_METRICS.SESSION_TURNS_TOTAL,
146
+ type: 'counter',
147
+ value: counts.completed,
148
+ labels: { status: 'completed', ...labels },
149
+ }))
150
+ }
151
+ if (counts.abandoned > 0) {
152
+ records.push(emit({
153
+ name: SEVO_METRICS.SESSION_TURNS_TOTAL,
154
+ type: 'counter',
155
+ value: counts.abandoned,
156
+ labels: { status: 'abandoned', ...labels },
157
+ }))
158
+ }
159
+ return records
160
+ },
161
+
162
+ recordWebVital(name, value, labels = {}) {
163
+ if (value == null || Number.isNaN(value)) return
164
+ return emit({
165
+ name: SEVO_METRICS.WEB_VITAL,
166
+ type: 'histogram',
167
+ value: Math.max(0, value),
168
+ labels: { vital: name || 'unknown', ...labels },
169
+ })
170
+ },
171
+
172
+ recordBusEvent(eventName, labels = {}) {
173
+ return emit({
174
+ name: SEVO_METRICS.BUS_EVENTS_TOTAL,
175
+ type: 'counter',
176
+ value: 1,
177
+ labels: { event: eventName || 'unknown', ...labels },
178
+ })
179
+ },
180
+
181
+ recordCustomMetric(metricName, labels = {}) {
182
+ return emit({
183
+ name: SEVO_METRICS.CUSTOM_METRICS_TOTAL,
184
+ type: 'counter',
185
+ value: 1,
186
+ labels: { metric: metricName || 'unknown', ...labels },
187
+ })
188
+ },
189
+
190
+ recordListenerDuration(durationMs, labels = {}) {
191
+ if (durationMs == null || Number.isNaN(durationMs)) return
192
+ return emit({
193
+ name: SEVO_METRICS.LISTENER_DURATION,
194
+ type: 'histogram',
195
+ value: Math.max(0, durationMs),
196
+ labels,
197
+ })
198
+ },
199
+ }
200
+ }
@@ -0,0 +1,143 @@
1
+ import { isErrorEvent } from './isErrorEvent.js'
2
+
3
+ /**
4
+ * Tracks phases within a turn from bus events and manual start/end calls.
5
+ */
6
+ export function createPhaseTracker(options = {}) {
7
+ const phases = options.phases || []
8
+ const isError = options.isError || isErrorEvent
9
+ const onPhaseStart = options.onPhaseStart || (() => {})
10
+ const onPhaseEnd = options.onPhaseEnd || (() => {})
11
+ const onPhaseWait = options.onPhaseWait || (() => {})
12
+ const onRenderDuration = options.onRenderDuration || (() => {})
13
+ const onTurnStatus = options.onTurnStatus || (() => {})
14
+
15
+ const phaseByStartEvent = new Map(phases.map((phase) => [phase.startEvent, phase]))
16
+ const phaseByEndEvent = new Map(phases.map((phase) => [phase.endEvent, phase]))
17
+
18
+ /** @type {Map<string, TurnPhaseState>} */
19
+ const turns = new Map()
20
+
21
+ return {
22
+ onTurnAbandoned(event) {
23
+ turns.delete(event.turnId)
24
+ },
25
+
26
+ onTurnStart(event) {
27
+ turns.set(event.turnId, {
28
+ turnStartedAt: Date.now(),
29
+ openPhases: new Map(),
30
+ lastPhaseEndedAt: null,
31
+ hasError: false,
32
+ })
33
+ },
34
+
35
+ onTurnEnd(event, labels = {}) {
36
+ const state = turns.get(event.turnId)
37
+ if (state?.lastPhaseEndedAt != null) {
38
+ const renderMs = Math.max(0, Date.now() - state.lastPhaseEndedAt)
39
+ onRenderDuration(renderMs, { ...labels, phase: 'render' })
40
+ }
41
+ onTurnStatus(state?.hasError ? 'error' : 'completed', labels)
42
+ turns.delete(event.turnId)
43
+ },
44
+
45
+ onBusEvent(event, labels = {}) {
46
+ if (!event.turnId) return
47
+
48
+ const state = turns.get(event.turnId)
49
+ if (!state) return
50
+
51
+ markErrorIfNeeded(state, event)
52
+
53
+ const startPhase = phaseByStartEvent.get(event.name)
54
+ if (startPhase) {
55
+ beginPhase(state, event.turnId, startPhase.id, labels, 'bus')
56
+ return
57
+ }
58
+
59
+ const endPhase = phaseByEndEvent.get(event.name)
60
+ if (endPhase) {
61
+ finishPhase(state, event.turnId, endPhase.id, labels, 'bus')
62
+ }
63
+ },
64
+
65
+ startPhase(turnId, phaseId, labels = {}) {
66
+ if (!turnId || !phaseId) return false
67
+ const state = turns.get(turnId)
68
+ if (!state) return false
69
+ beginPhase(state, turnId, String(phaseId), labels, 'manual')
70
+ return true
71
+ },
72
+
73
+ endPhase(turnId, phaseId, labels = {}) {
74
+ if (!turnId || !phaseId) return false
75
+ const state = turns.get(turnId)
76
+ if (!state) return false
77
+ return finishPhase(state, turnId, String(phaseId), labels, 'manual')
78
+ },
79
+
80
+ getTurnState(turnId) {
81
+ return turns.get(turnId) || null
82
+ },
83
+
84
+ clear() {
85
+ turns.clear()
86
+ },
87
+ }
88
+
89
+ function beginPhase(state, turnId, phaseId, labels, source) {
90
+ if (state.openPhases.has(phaseId)) return
91
+
92
+ if (state.turnStartedAt != null) {
93
+ const waitMs = Math.max(0, Date.now() - state.turnStartedAt)
94
+ onPhaseWait({
95
+ turnId,
96
+ phase: phaseId,
97
+ waitMs,
98
+ source,
99
+ labels,
100
+ })
101
+ }
102
+
103
+ state.openPhases.set(phaseId, { startedAt: Date.now(), source })
104
+ onPhaseStart({
105
+ turnId,
106
+ phase: phaseId,
107
+ source,
108
+ labels,
109
+ })
110
+ }
111
+
112
+ function finishPhase(state, turnId, phaseId, labels, source) {
113
+ const open = state.openPhases.get(phaseId)
114
+ if (!open) return false
115
+
116
+ const durationMs = Math.max(0, Date.now() - open.startedAt)
117
+ state.openPhases.delete(phaseId)
118
+ state.lastPhaseEndedAt = Date.now()
119
+
120
+ onPhaseEnd({
121
+ turnId,
122
+ phase: phaseId,
123
+ durationMs,
124
+ source: open.source || source,
125
+ labels,
126
+ })
127
+ return true
128
+ }
129
+
130
+ function markErrorIfNeeded(state, event) {
131
+ if (isError(event) && !state.hasError) {
132
+ state.hasError = true
133
+ }
134
+ }
135
+ }
136
+
137
+ /**
138
+ * @typedef {object} TurnPhaseState
139
+ * @property {number} turnStartedAt
140
+ * @property {Map<string, { startedAt: number, source: string }>} openPhases
141
+ * @property {number | null} lastPhaseEndedAt
142
+ * @property {boolean} hasError
143
+ */