@senpi-ai/runtime 3.0.151 → 3.0.155

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 (94) hide show
  1. package/dist/actions/action-events.d.ts +4 -4
  2. package/dist/actions/action-events.d.ts.map +1 -1
  3. package/dist/actions/action-events.js +17 -7
  4. package/dist/actions/action-events.js.map +1 -1
  5. package/dist/actions/event-derivation.d.ts.map +1 -1
  6. package/dist/actions/event-derivation.js +17 -2
  7. package/dist/actions/event-derivation.js.map +1 -1
  8. package/dist/actions/open-position/open-position.action.d.ts.map +1 -1
  9. package/dist/actions/open-position/open-position.action.js +8 -3
  10. package/dist/actions/open-position/open-position.action.js.map +1 -1
  11. package/dist/cli/guide-commands.d.ts.map +1 -1
  12. package/dist/cli/guide-commands.js +2 -1
  13. package/dist/cli/guide-commands.js.map +1 -1
  14. package/dist/constants/telemetry.d.ts +19 -0
  15. package/dist/constants/telemetry.d.ts.map +1 -0
  16. package/dist/constants/telemetry.js +32 -0
  17. package/dist/constants/telemetry.js.map +1 -0
  18. package/dist/dsl/monitor/process-one-position.d.ts.map +1 -1
  19. package/dist/dsl/monitor/process-one-position.js +6 -2
  20. package/dist/dsl/monitor/process-one-position.js.map +1 -1
  21. package/dist/dsl/plugin/index.d.ts +0 -1
  22. package/dist/dsl/plugin/index.d.ts.map +1 -1
  23. package/dist/dsl/plugin/index.js +4 -17
  24. package/dist/dsl/plugin/index.js.map +1 -1
  25. package/dist/health/types.d.ts +10 -0
  26. package/dist/health/types.d.ts.map +1 -1
  27. package/dist/index.d.ts +4 -0
  28. package/dist/index.d.ts.map +1 -1
  29. package/dist/index.js +77 -1
  30. package/dist/index.js.map +1 -1
  31. package/dist/runtime/domain-events.d.ts.map +1 -1
  32. package/dist/runtime/domain-events.js +2 -0
  33. package/dist/runtime/domain-events.js.map +1 -1
  34. package/dist/runtime/events-telemetry.d.ts +120 -0
  35. package/dist/runtime/events-telemetry.d.ts.map +1 -0
  36. package/dist/runtime/events-telemetry.js +314 -0
  37. package/dist/runtime/events-telemetry.js.map +1 -0
  38. package/dist/runtime/risk-guard.d.ts +20 -5
  39. package/dist/runtime/risk-guard.d.ts.map +1 -1
  40. package/dist/runtime/risk-guard.js +111 -23
  41. package/dist/runtime/risk-guard.js.map +1 -1
  42. package/dist/runtime/run.d.ts +7 -0
  43. package/dist/runtime/run.d.ts.map +1 -1
  44. package/dist/runtime/run.js +7 -0
  45. package/dist/runtime/run.js.map +1 -1
  46. package/dist/runtime/runtime.d.ts +21 -0
  47. package/dist/runtime/runtime.d.ts.map +1 -1
  48. package/dist/runtime/runtime.js +51 -3
  49. package/dist/runtime/runtime.js.map +1 -1
  50. package/dist/runtime/strategies-store.d.ts +26 -0
  51. package/dist/runtime/strategies-store.d.ts.map +1 -0
  52. package/dist/runtime/strategies-store.js +47 -0
  53. package/dist/runtime/strategies-store.js.map +1 -0
  54. package/dist/runtime/strategies-telemetry.d.ts +124 -0
  55. package/dist/runtime/strategies-telemetry.d.ts.map +1 -0
  56. package/dist/runtime/strategies-telemetry.js +143 -0
  57. package/dist/runtime/strategies-telemetry.js.map +1 -0
  58. package/dist/runtime/strategy-lifecycle.d.ts +36 -13
  59. package/dist/runtime/strategy-lifecycle.d.ts.map +1 -1
  60. package/dist/runtime/strategy-lifecycle.js +120 -71
  61. package/dist/runtime/strategy-lifecycle.js.map +1 -1
  62. package/dist/runtime-api/intake/intake-mount.d.ts +2 -0
  63. package/dist/runtime-api/intake/intake-mount.d.ts.map +1 -1
  64. package/dist/runtime-api/intake/intake-mount.js +6 -3
  65. package/dist/runtime-api/intake/intake-mount.js.map +1 -1
  66. package/dist/runtime-api/routes/signals.d.ts.map +1 -1
  67. package/dist/runtime-api/routes/signals.js +10 -0
  68. package/dist/runtime-api/routes/signals.js.map +1 -1
  69. package/dist/state/state-manager.d.ts +2 -0
  70. package/dist/state/state-manager.d.ts.map +1 -1
  71. package/dist/state/state-manager.js +8 -0
  72. package/dist/state/state-manager.js.map +1 -1
  73. package/dist/telemetry/event-builders.d.ts +8 -2
  74. package/dist/telemetry/event-builders.d.ts.map +1 -1
  75. package/dist/telemetry/event-builders.js +6 -0
  76. package/dist/telemetry/event-builders.js.map +1 -1
  77. package/dist/telemetry/event-store.d.ts +30 -7
  78. package/dist/telemetry/event-store.d.ts.map +1 -1
  79. package/dist/telemetry/event-store.js +114 -20
  80. package/dist/telemetry/event-store.js.map +1 -1
  81. package/dist/telemetry/spans/redact-pii.d.ts.map +1 -1
  82. package/dist/telemetry/spans/redact-pii.js +19 -2
  83. package/dist/telemetry/spans/redact-pii.js.map +1 -1
  84. package/dist/types/action.d.ts +27 -7
  85. package/dist/types/action.d.ts.map +1 -1
  86. package/dist/utils/event-catalog.d.ts +9 -1
  87. package/dist/utils/event-catalog.d.ts.map +1 -1
  88. package/dist/utils/event-catalog.js.map +1 -1
  89. package/dist/utils/logger.d.ts +5 -3
  90. package/dist/utils/logger.d.ts.map +1 -1
  91. package/dist/utils/logger.js +39 -28
  92. package/dist/utils/logger.js.map +1 -1
  93. package/openclaw.plugin.json +1 -1
  94. package/package.json +1 -1
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Events telemetry: the in-memory buffer of runtime event records, the tap that fills it from the
3
+ * per-wallet event sink, and the loop that broadcasts new records as `plugin.senpi.events`.
4
+ */
5
+ import { type EventSink, type StoredEvent } from "../telemetry/event-store.js";
6
+ import { type PiiRedactor } from "../telemetry/spans/redact-pii.js";
7
+ import { type LogLevel } from "../utils/logger.js";
8
+ import { type StrategiesBroadcastFn } from "./strategies-telemetry.js";
9
+ /** One event as broadcast. `address` is the wallet whose sink received the event. */
10
+ export interface EventRecord {
11
+ seq: number;
12
+ ts: number;
13
+ name: string;
14
+ level: LogLevel;
15
+ address: string;
16
+ body: string;
17
+ attrs: Record<string, string | number | boolean>;
18
+ }
19
+ export interface EventsMessage {
20
+ v: 1;
21
+ epoch: string;
22
+ batchSeq: number;
23
+ events: EventRecord[];
24
+ }
25
+ export interface EventsReplay {
26
+ epoch: string;
27
+ events: EventRecord[];
28
+ truncated: boolean;
29
+ }
30
+ export interface EventsCursor {
31
+ afterEpoch: string;
32
+ afterSeq: number;
33
+ }
34
+ export interface EventsBuffer {
35
+ /** Gives the event the next `seq` and appends it to the ring of `address`. */
36
+ add(address: string, event: StoredEvent): void;
37
+ /** Held records with `seq` greater than `seq`, in `seq` order. */
38
+ after(seq: number): EventRecord[];
39
+ /** The highest `seq` held in any ring, `0` when nothing is held. */
40
+ newestSeq(): number;
41
+ /**
42
+ * The highest `seq` evicted from any ring, `0` when nothing was evicted. Deleting a closed ring
43
+ * evicts its records.
44
+ */
45
+ maxEvictedSeq(): number;
46
+ /**
47
+ * Closes the ring of `address`. A closed ring takes no new records and stays in `after` until
48
+ * `dropSent` deletes it. The next record for `address` starts a new, empty ring. Closing does not
49
+ * change `maxEvictedSeq`.
50
+ */
51
+ remove(address: string): void;
52
+ /**
53
+ * Deletes each closed ring whose newest `seq` is at most `sentSeq`, and each closed ring closed at
54
+ * least `EVENTS_CLOSED_RING_TTL_MS` ago. `maxEvictedSeq` rises to the newest `seq` of each deleted ring.
55
+ */
56
+ dropSent(sentSeq: number): void;
57
+ }
58
+ /**
59
+ * One ring of `capacity` records per address. `seq` starts at 1 and counts across every address.
60
+ * `now` is the clock, in epoch ms, that times a closed ring.
61
+ */
62
+ export declare function createEventsBuffer(capacity?: number, now?: () => number): EventsBuffer;
63
+ /** The process buffer. Its `seq` run belongs to `PROCESS_EPOCH`. */
64
+ export declare const eventsBuffer: EventsBuffer;
65
+ /**
66
+ * Adds a record to `buffer` under `address` for a case that is not a runtime event. It does not go
67
+ * through `logger.event`, so no event sink, disk ring or OTel record receives it. A blank `address`
68
+ * adds nothing. Never throws.
69
+ */
70
+ export declare function addEventRecord(address: string, event: StoredEvent, buffer?: EventsBuffer): void;
71
+ /**
72
+ * Wraps a wallet's event sink. Every event goes to `sink`. An event whose name is in
73
+ * `EVENTS_BROADCAST_NAMES` is also added to `buffer` under `address`.
74
+ */
75
+ export declare function withEventsTap(address: string, sink: EventSink, buffer?: EventsBuffer): EventSink;
76
+ /**
77
+ * A copy of the record with every string in `body` and `attrs` run through the redactor, except the
78
+ * join-id attrs in `UNSCRUBBED_ATTRS`. A string attr the redactor cannot produce is left out; such a
79
+ * `body` becomes `""`.
80
+ */
81
+ export declare function scrubEventRecord(record: EventRecord, redactor: PiiRedactor): Promise<EventRecord>;
82
+ /**
83
+ * The events part of the subscribe reply. A cursor whose `afterEpoch` is `epoch` selects the held
84
+ * records after `afterSeq`; any other cursor, or none, selects every held record. The newest
85
+ * selected records that fit `maxBytes` are served, scrubbed, in `seq` order. `truncated` is `true`
86
+ * when a record owed to the cursor was evicted, or a selected record was not served. A cursor of
87
+ * the current epoch is owed the records after `afterSeq`; a cursor of another epoch is owed every
88
+ * record of the current epoch; no cursor is owed nothing. Without a redactor no record is served.
89
+ */
90
+ export declare function buildEventsReplay(input: {
91
+ buffer?: EventsBuffer;
92
+ epoch?: string;
93
+ cursor?: EventsCursor;
94
+ redactor: PiiRedactor | null;
95
+ maxBytes?: number;
96
+ }): Promise<EventsReplay>;
97
+ export interface EventsPublisher {
98
+ /** Sends every interval. A second call while running does nothing. */
99
+ start(): void;
100
+ /** Stops the sends. */
101
+ stop(): void;
102
+ }
103
+ /**
104
+ * Each tick takes the records added since the previous tick. With a broadcast function, it scrubs
105
+ * them and broadcasts them as one or more messages of at most `maxFrameBytes` serialized bytes. A
106
+ * record that does not fit an empty message is dropped and passed to `warn`. Without a broadcast
107
+ * function, the records are not sent. While there is no redactor, the tick sends nothing and keeps
108
+ * the records for the first tick that has one. Each tick ends with `dropSent`: it deletes the closed
109
+ * rings whose records it has passed, and the closed rings held past `EVENTS_CLOSED_RING_TTL_MS`.
110
+ */
111
+ export declare function createEventsPublisher(deps: {
112
+ getBroadcast: () => StrategiesBroadcastFn | undefined;
113
+ buffer?: EventsBuffer;
114
+ getRedactor?: () => PiiRedactor | null;
115
+ epoch?: string;
116
+ maxFrameBytes?: number;
117
+ warn?: (message: string, meta: Record<string, unknown>) => void;
118
+ onError?: (err: unknown) => void;
119
+ }): EventsPublisher;
120
+ //# sourceMappingURL=events-telemetry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"events-telemetry.d.ts","sourceRoot":"","sources":["../../src/runtime/events-telemetry.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,314 @@
1
+ /**
2
+ * Events telemetry: the in-memory buffer of runtime event records, the tap that fills it from the
3
+ * per-wallet event sink, and the loop that broadcasts new records as `plugin.senpi.events`.
4
+ */
5
+ import { EVENTS_BROADCAST_NAMES, EVENTS_CLOSED_RING_TTL_MS, EVENTS_EVENT_NAME, EVENTS_MAX_BODY_CHARS, EVENTS_MAX_FRAME_BYTES, EVENTS_PER_STRATEGY, EVENTS_SEND_INTERVAL_MS, } from "../constants/telemetry.js";
6
+ import { capValue } from "../telemetry/attributes.js";
7
+ import { normalizeStrategyAddress } from "../telemetry/event-store.js";
8
+ import { getDefaultPiiRedactor } from "../telemetry/spans/redact-pii.js";
9
+ import { JOIN_ATTR } from "../utils/event-catalog.js";
10
+ import { createLogger } from "../utils/logger.js";
11
+ import { PROCESS_EPOCH } from "./strategies-telemetry.js";
12
+ const logger = createLogger("[runtime][events-telemetry]");
13
+ const BROADCAST_NAMES = new Set(EVENTS_BROADCAST_NAMES);
14
+ /**
15
+ * One ring of `capacity` records per address. `seq` starts at 1 and counts across every address.
16
+ * `now` is the clock, in epoch ms, that times a closed ring.
17
+ */
18
+ export function createEventsBuffer(capacity = EVENTS_PER_STRATEGY, now = () => Date.now()) {
19
+ const rings = new Map();
20
+ // Rings closed by `remove`, each with the time it was closed. Kept apart from `rings` so a new
21
+ // ring for the same address never mixes with them.
22
+ const closed = new Map();
23
+ let seq = 0;
24
+ let maxEvicted = 0;
25
+ return {
26
+ add(address, event) {
27
+ const key = normalizeStrategyAddress(address);
28
+ const attrs = {};
29
+ for (const [k, v] of Object.entries(event.attrs)) {
30
+ if (typeof v === "string" || typeof v === "boolean" || (typeof v === "number" && Number.isFinite(v)))
31
+ attrs[k] = v;
32
+ }
33
+ let body = capValue(event.body, EVENTS_MAX_BODY_CHARS);
34
+ // A truncated body is a slice of the original string, and V8 keeps the whole original alive
35
+ // behind a slice. A JSON round trip stores an exact, flat copy of the capped length only.
36
+ if (body !== event.body)
37
+ body = JSON.parse(JSON.stringify(body));
38
+ let ring = rings.get(key);
39
+ if (ring === undefined) {
40
+ ring = [];
41
+ rings.set(key, ring);
42
+ }
43
+ ring.push({ seq: ++seq, ts: event.ts, name: event.name, level: event.level, address: key, body, attrs });
44
+ if (ring.length > capacity)
45
+ maxEvicted = Math.max(maxEvicted, ring.shift().seq);
46
+ },
47
+ after(after) {
48
+ const out = [];
49
+ const collect = (ring) => {
50
+ let i = ring.length;
51
+ while (i > 0 && ring[i - 1].seq > after)
52
+ i--;
53
+ for (; i < ring.length; i++)
54
+ out.push(ring[i]);
55
+ };
56
+ for (const ring of rings.values())
57
+ collect(ring);
58
+ for (const ring of closed.keys())
59
+ collect(ring);
60
+ return out.sort((a, b) => a.seq - b.seq);
61
+ },
62
+ newestSeq() {
63
+ let newest = 0;
64
+ for (const ring of rings.values()) {
65
+ if (ring.length > 0)
66
+ newest = Math.max(newest, ring[ring.length - 1].seq);
67
+ }
68
+ // A closed ring is never empty.
69
+ for (const ring of closed.keys())
70
+ newest = Math.max(newest, ring[ring.length - 1].seq);
71
+ return newest;
72
+ },
73
+ maxEvictedSeq: () => maxEvicted,
74
+ remove(address) {
75
+ const key = normalizeStrategyAddress(address);
76
+ const ring = rings.get(key);
77
+ if (ring === undefined)
78
+ return;
79
+ rings.delete(key);
80
+ if (ring.length > 0)
81
+ closed.set(ring, now());
82
+ },
83
+ dropSent(sentSeq) {
84
+ const expiredAt = now() - EVENTS_CLOSED_RING_TTL_MS;
85
+ for (const [ring, closedAt] of closed) {
86
+ const newest = ring[ring.length - 1].seq;
87
+ if (newest > sentSeq && closedAt > expiredAt)
88
+ continue;
89
+ closed.delete(ring);
90
+ maxEvicted = Math.max(maxEvicted, newest);
91
+ }
92
+ },
93
+ };
94
+ }
95
+ /** The process buffer. Its `seq` run belongs to `PROCESS_EPOCH`. */
96
+ export const eventsBuffer = createEventsBuffer();
97
+ /**
98
+ * Adds a record to `buffer` under `address` for a case that is not a runtime event. It does not go
99
+ * through `logger.event`, so no event sink, disk ring or OTel record receives it. A blank `address`
100
+ * adds nothing. Never throws.
101
+ */
102
+ export function addEventRecord(address, event, buffer = eventsBuffer) {
103
+ try {
104
+ if (normalizeStrategyAddress(address) !== "")
105
+ buffer.add(address, event);
106
+ }
107
+ catch (err) {
108
+ // Callers are request handlers; a buffer failure must not fail the request.
109
+ logger.debug("addEventRecord failed", { address, name: event.name, err });
110
+ }
111
+ }
112
+ /**
113
+ * Wraps a wallet's event sink. Every event goes to `sink`. An event whose name is in
114
+ * `EVENTS_BROADCAST_NAMES` is also added to `buffer` under `address`.
115
+ */
116
+ export function withEventsTap(address, sink, buffer = eventsBuffer) {
117
+ return {
118
+ append(event) {
119
+ sink.append(event);
120
+ try {
121
+ if (BROADCAST_NAMES.has(event.name))
122
+ buffer.add(address, event);
123
+ }
124
+ catch {
125
+ // The tap runs inside `logger.event` and must not throw into it.
126
+ }
127
+ },
128
+ flush: () => sink.flush(),
129
+ };
130
+ }
131
+ /** The redacted value, or `undefined` when the redactor throws. `""` is kept as is. */
132
+ async function scrubString(value, redactor) {
133
+ if (value === "")
134
+ return value;
135
+ try {
136
+ const out = await redactor.redact(value);
137
+ return typeof out === "string" ? out : undefined;
138
+ }
139
+ catch {
140
+ return undefined;
141
+ }
142
+ }
143
+ /** Join-id attrs. They hold ids, never free text, and are sent as they are. */
144
+ const UNSCRUBBED_ATTRS = new Set([
145
+ ...Object.values(JOIN_ATTR),
146
+ "senpi.strategy.address",
147
+ "senpi.scanner.id",
148
+ ]);
149
+ /**
150
+ * A copy of the record with every string in `body` and `attrs` run through the redactor, except the
151
+ * join-id attrs in `UNSCRUBBED_ATTRS`. A string attr the redactor cannot produce is left out; such a
152
+ * `body` becomes `""`.
153
+ */
154
+ export async function scrubEventRecord(record, redactor) {
155
+ const attrs = {};
156
+ for (const [key, value] of Object.entries(record.attrs)) {
157
+ if (typeof value !== "string" || UNSCRUBBED_ATTRS.has(key)) {
158
+ attrs[key] = value;
159
+ continue;
160
+ }
161
+ const scrubbed = await scrubString(value, redactor);
162
+ if (scrubbed !== undefined)
163
+ attrs[key] = scrubbed;
164
+ }
165
+ return { ...record, body: (await scrubString(record.body, redactor)) ?? "", attrs };
166
+ }
167
+ const bytes = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
168
+ /**
169
+ * Fills one frame of records: a JSON envelope of `envelopeBytes` whose `events` array holds the
170
+ * records, at most `maxBytes` serialized in total. `offer` answers `"added"`, `"full"` (the record
171
+ * does not fit what is already in the frame; it is not added) or `"oversize"` (the record does not
172
+ * fit an empty frame; it is not added). `take` returns the frame and starts an empty one.
173
+ */
174
+ function createFramePacker(envelopeBytes, maxBytes) {
175
+ let frame = [];
176
+ let used = envelopeBytes;
177
+ return {
178
+ offer(record) {
179
+ const size = bytes(record);
180
+ if (envelopeBytes + size > maxBytes)
181
+ return { result: "oversize", bytes: size };
182
+ // One comma between two records.
183
+ const added = size + (frame.length > 0 ? 1 : 0);
184
+ if (used + added > maxBytes)
185
+ return { result: "full", bytes: size };
186
+ used += added;
187
+ frame.push(record);
188
+ return { result: "added", bytes: size };
189
+ },
190
+ take() {
191
+ const out = frame;
192
+ frame = [];
193
+ used = envelopeBytes;
194
+ return out;
195
+ },
196
+ };
197
+ }
198
+ /**
199
+ * The events part of the subscribe reply. A cursor whose `afterEpoch` is `epoch` selects the held
200
+ * records after `afterSeq`; any other cursor, or none, selects every held record. The newest
201
+ * selected records that fit `maxBytes` are served, scrubbed, in `seq` order. `truncated` is `true`
202
+ * when a record owed to the cursor was evicted, or a selected record was not served. A cursor of
203
+ * the current epoch is owed the records after `afterSeq`; a cursor of another epoch is owed every
204
+ * record of the current epoch; no cursor is owed nothing. Without a redactor no record is served.
205
+ */
206
+ export async function buildEventsReplay(input) {
207
+ const buffer = input.buffer ?? eventsBuffer;
208
+ const epoch = input.epoch ?? PROCESS_EPOCH;
209
+ const maxBytes = input.maxBytes ?? EVENTS_MAX_FRAME_BYTES;
210
+ const redactor = input.redactor;
211
+ const afterSeq = input.cursor?.afterEpoch === epoch ? input.cursor.afterSeq : undefined;
212
+ let truncated = input.cursor !== undefined && buffer.maxEvictedSeq() > (afterSeq ?? 0);
213
+ if (redactor === null)
214
+ return { epoch, events: [], truncated: truncated || buffer.newestSeq() > (afterSeq ?? 0) };
215
+ const selected = buffer.after(afterSeq ?? 0);
216
+ const packer = createFramePacker(bytes({ epoch, events: [], truncated: false }), maxBytes);
217
+ // Newest first, one record at a time, until the frame is full.
218
+ for (let i = selected.length - 1; i >= 0; i--) {
219
+ const { result } = packer.offer(await scrubEventRecord(selected[i], redactor));
220
+ if (result === "added")
221
+ continue;
222
+ truncated = true;
223
+ // An oversize record is skipped and the older records are still served. A full reply ends here.
224
+ if (result === "full")
225
+ break;
226
+ }
227
+ return { epoch, events: packer.take().reverse(), truncated };
228
+ }
229
+ /**
230
+ * Each tick takes the records added since the previous tick. With a broadcast function, it scrubs
231
+ * them and broadcasts them as one or more messages of at most `maxFrameBytes` serialized bytes. A
232
+ * record that does not fit an empty message is dropped and passed to `warn`. Without a broadcast
233
+ * function, the records are not sent. While there is no redactor, the tick sends nothing and keeps
234
+ * the records for the first tick that has one. Each tick ends with `dropSent`: it deletes the closed
235
+ * rings whose records it has passed, and the closed rings held past `EVENTS_CLOSED_RING_TTL_MS`.
236
+ */
237
+ export function createEventsPublisher(deps) {
238
+ const buffer = deps.buffer ?? eventsBuffer;
239
+ const getRedactor = deps.getRedactor ?? getDefaultPiiRedactor;
240
+ const epoch = deps.epoch ?? PROCESS_EPOCH;
241
+ const maxFrameBytes = deps.maxFrameBytes ?? EVENTS_MAX_FRAME_BYTES;
242
+ // Upper bound of the message without its records.
243
+ const envelopeBytes = bytes({ v: 1, epoch, batchSeq: Number.MAX_SAFE_INTEGER, events: [] });
244
+ let lastSeq = 0;
245
+ let batchSeq = 0;
246
+ let timer;
247
+ let inFlight = false;
248
+ const send = (broadcast, events) => {
249
+ const message = { v: 1, epoch, batchSeq: ++batchSeq, events };
250
+ broadcast(EVENTS_EVENT_NAME, message, { dropIfSlow: true });
251
+ };
252
+ const tick = async () => {
253
+ if (inFlight)
254
+ return;
255
+ inFlight = true;
256
+ try {
257
+ if (deps.getBroadcast() === undefined) {
258
+ lastSeq = Math.max(lastSeq, buffer.newestSeq());
259
+ return;
260
+ }
261
+ const redactor = getRedactor();
262
+ if (redactor === null)
263
+ return;
264
+ const records = buffer.after(lastSeq);
265
+ if (records.length === 0)
266
+ return;
267
+ lastSeq = records[records.length - 1].seq;
268
+ const scrubbed = await Promise.all(records.map((record) => scrubEventRecord(record, redactor)));
269
+ const broadcast = deps.getBroadcast();
270
+ if (broadcast === undefined || timer === undefined)
271
+ return;
272
+ const packer = createFramePacker(envelopeBytes, maxFrameBytes);
273
+ for (const record of scrubbed) {
274
+ let offered = packer.offer(record);
275
+ if (offered.result === "full") {
276
+ send(broadcast, packer.take());
277
+ offered = packer.offer(record);
278
+ }
279
+ if (offered.result === "oversize") {
280
+ deps.warn?.("[senpi-runtime] event record exceeds the events frame size; dropped", {
281
+ seq: record.seq,
282
+ name: record.name,
283
+ address: record.address,
284
+ bytes: offered.bytes,
285
+ });
286
+ }
287
+ }
288
+ const last = packer.take();
289
+ if (last.length > 0)
290
+ send(broadcast, last);
291
+ }
292
+ catch (err) {
293
+ deps.onError?.(err);
294
+ }
295
+ finally {
296
+ buffer.dropSent(lastSeq);
297
+ inFlight = false;
298
+ }
299
+ };
300
+ return {
301
+ start() {
302
+ if (timer !== undefined)
303
+ return;
304
+ timer = setInterval(() => void tick(), EVENTS_SEND_INTERVAL_MS);
305
+ timer.unref?.();
306
+ },
307
+ stop() {
308
+ if (timer !== undefined)
309
+ clearInterval(timer);
310
+ timer = undefined;
311
+ },
312
+ };
313
+ }
314
+ //# sourceMappingURL=events-telemetry.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"events-telemetry.js","sourceRoot":"","sources":["../../src/runtime/events-telemetry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAoC,MAAM,6BAA6B,CAAC;AACzG,OAAO,EAAE,qBAAqB,EAAoB,MAAM,kCAAkC,CAAC;AAC3F,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,YAAY,EAAiB,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,aAAa,EAA8B,MAAM,2BAA2B,CAAC;AAEtF,MAAM,MAAM,GAAG,YAAY,CAAC,6BAA6B,CAAC,CAAC;AAwD3D,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC,sBAAsB,CAAC,CAAC;AAE7E;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB,mBAAmB,EAAE,MAAoB,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;IAC7G,MAAM,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC/C,+FAA+F;IAC/F,mDAAmD;IACnD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAyB,CAAC;IAChD,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,OAAO;QACL,GAAG,CAAC,OAAO,EAAE,KAAK;YAChB,MAAM,GAAG,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;YAC9C,MAAM,KAAK,GAAyB,EAAE,CAAC;YACvC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;oBAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACrH,CAAC;YACD,IAAI,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC;YACvD,4FAA4F;YAC5F,0FAA0F;YAC1F,IAAI,IAAI,KAAK,KAAK,CAAC,IAAI;gBAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAW,CAAC;YAC3E,IAAI,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC1B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,IAAI,GAAG,EAAE,CAAC;gBACV,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACvB,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACzG,IAAI,IAAI,CAAC,MAAM,GAAG,QAAQ;gBAAE,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,EAAG,CAAC,GAAG,CAAC,CAAC;QACnF,CAAC;QACD,KAAK,CAAC,KAAK;YACT,MAAM,GAAG,GAAkB,EAAE,CAAC;YAC9B,MAAM,OAAO,GAAG,CAAC,IAAmB,EAAQ,EAAE;gBAC5C,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;gBACpB,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK;oBAAE,CAAC,EAAE,CAAC;gBAC7C,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE;oBAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YACjD,CAAC,CAAC;YACF,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE;gBAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YACjD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE;gBAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YAChD,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QAC3C,CAAC;QACD,SAAS;YACP,IAAI,MAAM,GAAG,CAAC,CAAC;YACf,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBAClC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;oBAAE,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAC5E,CAAC;YACD,gCAAgC;YAChC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE;gBAAE,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACvF,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,aAAa,EAAE,GAAG,EAAE,CAAC,UAAU;QAC/B,MAAM,CAAC,OAAO;YACZ,MAAM,GAAG,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;YAC9C,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO;YAC/B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAClB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;QAC/C,CAAC;QACD,QAAQ,CAAC,OAAO;YACd,MAAM,SAAS,GAAG,GAAG,EAAE,GAAG,yBAAyB,CAAC;YACpD,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,EAAE,CAAC;gBACtC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;gBACzC,IAAI,MAAM,GAAG,OAAO,IAAI,QAAQ,GAAG,SAAS;oBAAE,SAAS;gBACvD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBACpB,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,oEAAoE;AACpE,MAAM,CAAC,MAAM,YAAY,GAAiB,kBAAkB,EAAE,CAAC;AAE/D;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,KAAkB,EAAE,SAAuB,YAAY;IACrG,IAAI,CAAC;QACH,IAAI,wBAAwB,CAAC,OAAO,CAAC,KAAK,EAAE;YAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC3E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,4EAA4E;QAC5E,MAAM,CAAC,KAAK,CAAC,uBAAuB,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;IAC5E,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,IAAe,EAAE,SAAuB,YAAY;IACjG,OAAO;QACL,MAAM,CAAC,KAAK;YACV,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnB,IAAI,CAAC;gBACH,IAAI,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;oBAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YAClE,CAAC;YAAC,MAAM,CAAC;gBACP,iEAAiE;YACnE,CAAC;QACH,CAAC;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE;KAC1B,CAAC;AACJ,CAAC;AAED,uFAAuF;AACvF,KAAK,UAAU,WAAW,CAAC,KAAa,EAAE,QAAqB;IAC7D,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC/B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACzC,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC;IACpD,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC;IAC3B,wBAAwB;IACxB,kBAAkB;CACnB,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAmB,EAAE,QAAqB;IAC/E,MAAM,KAAK,GAAyB,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACxD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3D,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACnB,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACpD,IAAI,QAAQ,KAAK,SAAS;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;IACpD,CAAC;IACD,OAAO,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,CAAC,MAAM,WAAW,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC;AACtF,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,KAAc,EAAU,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;AAE3F;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,aAAqB,EAAE,QAAgB;IAChE,IAAI,KAAK,GAAkB,EAAE,CAAC;IAC9B,IAAI,IAAI,GAAG,aAAa,CAAC;IACzB,OAAO;QACL,KAAK,CAAC,MAAmB;YACvB,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;YAC3B,IAAI,aAAa,GAAG,IAAI,GAAG,QAAQ;gBAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YAChF,iCAAiC;YACjC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAChD,IAAI,IAAI,GAAG,KAAK,GAAG,QAAQ;gBAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YACpE,IAAI,IAAI,KAAK,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACnB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC1C,CAAC;QACD,IAAI;YACF,MAAM,GAAG,GAAG,KAAK,CAAC;YAClB,KAAK,GAAG,EAAE,CAAC;YACX,IAAI,GAAG,aAAa,CAAC;YACrB,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAMvC;IACC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,YAAY,CAAC;IAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,aAAa,CAAC;IAC3C,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,sBAAsB,CAAC;IAC1D,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,UAAU,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IACxF,IAAI,SAAS,GAAG,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,aAAa,EAAE,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;IACvF,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,IAAI,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC,EAAE,CAAC;IAElH,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC3F,+DAA+D;IAC/D,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC/E,IAAI,MAAM,KAAK,OAAO;YAAE,SAAS;QACjC,SAAS,GAAG,IAAI,CAAC;QACjB,gGAAgG;QAChG,IAAI,MAAM,KAAK,MAAM;YAAE,MAAM;IAC/B,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,CAAC;AAC/D,CAAC;AASD;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAQrC;IACC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,YAAY,CAAC;IAC3C,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,qBAAqB,CAAC;IAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,aAAa,CAAC;IAC1C,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,sBAAsB,CAAC;IACnE,kDAAkD;IAClD,MAAM,aAAa,GAAG,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;IAC5F,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,KAAiD,CAAC;IACtD,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,MAAM,IAAI,GAAG,CAAC,SAAgC,EAAE,MAAqB,EAAQ,EAAE;QAC7E,MAAM,OAAO,GAAkB,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAC7E,SAAS,CAAC,iBAAiB,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,KAAK,IAAmB,EAAE;QACrC,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,IAAI,CAAC;YACH,IAAI,IAAI,CAAC,YAAY,EAAE,KAAK,SAAS,EAAE,CAAC;gBACtC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;gBAChD,OAAO;YACT,CAAC;YACD,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;YAC/B,IAAI,QAAQ,KAAK,IAAI;gBAAE,OAAO;YAC9B,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACtC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YACjC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;YAC1C,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;YAChG,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YACtC,IAAI,SAAS,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO;YAE3D,MAAM,MAAM,GAAG,iBAAiB,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;YAC/D,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;gBAC9B,IAAI,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBACnC,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;oBAC9B,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;oBAC/B,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBACjC,CAAC;gBACD,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;oBAClC,IAAI,CAAC,IAAI,EAAE,CAAC,qEAAqE,EAAE;wBACjF,GAAG,EAAE,MAAM,CAAC,GAAG;wBACf,IAAI,EAAE,MAAM,CAAC,IAAI;wBACjB,OAAO,EAAE,MAAM,CAAC,OAAO;wBACvB,KAAK,EAAE,OAAO,CAAC,KAAK;qBACrB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;YAC3B,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACzB,QAAQ,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,KAAK;YACH,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO;YAChC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,EAAE,EAAE,uBAAuB,CAAC,CAAC;YAChE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QAClB,CAAC;QACD,IAAI;YACF,IAAI,KAAK,KAAK,SAAS;gBAAE,aAAa,CAAC,KAAK,CAAC,CAAC;YAC9C,KAAK,GAAG,SAAS,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC"}
@@ -10,9 +10,16 @@
10
10
  * If any risk API call fails, the gate is CLOSED (fail-closed).
11
11
  *
12
12
  * Evaluation is stateless, but enforcement of the halt-class gates (daily loss, drawdown) is
13
- * not: each of their evaluations passes through the lifecycle tracker's `applyLatch`, which
13
+ * not: each live evaluation of them passes through the lifecycle tracker's `applyLatch`, which
14
14
  * keeps a genuinely-breached halt CLOSED until its release rule (UTC day rollover) fires, so a
15
- * mark-to-market bounce back under the limit cannot reopen entries mid-day.
15
+ * mark-to-market bounce back under the limit cannot reopen entries mid-day. Setting or releasing
16
+ * a latch there is what pauses or resumes the strategy for these two gates.
17
+ *
18
+ * A per-signal check skips the PnL snapshot fetch while the first snapshot-using halt gate (daily
19
+ * loss when configured, else drawdown) holds a latch that is active by the box clock. It returns
20
+ * that gate's latched block from `activeLatchBlock`, which never sets or releases a latch. When
21
+ * daily loss is configured and not latched, the snapshot is fetched as usual. `evaluateAll`
22
+ * (status and health) always fetches.
16
23
  *
17
24
  * Supports two modes:
18
25
  * - Default (short-circuit): returns on first non-OPEN gate.
@@ -40,9 +47,9 @@ export interface RiskGuardConfig {
40
47
  auditLog?: RiskAuditLog;
41
48
  /**
42
49
  * Optional strategy-lifecycle tracker. RiskGuard is stateless and only reports; the
43
- * lifecycle component owns the self-pause state (which gates are paused) and fires the
44
- * hook event + user notification on a running→paused transition. Optional so existing
45
- * call sites/tests don't break.
50
+ * lifecycle component owns the self-pause state and fires the hook event + user notification
51
+ * on a pause: from `observe` for the non-latched gates, from `applyLatch` for the latched ones.
52
+ * Optional so existing call sites/tests don't break.
46
53
  */
47
54
  lifecycleTracker?: {
48
55
  observe(address: string, label: string, evaluations: RiskGateEvaluation[], source: RiskSource): void;
@@ -52,7 +59,15 @@ export interface RiskGuardConfig {
52
59
  */
53
60
  applyLatch?(address: string, evaluation: RiskGateEvaluation, opts: {
54
61
  releaseOnDayRollover: boolean;
62
+ label?: string;
55
63
  }): Promise<RiskGateEvaluation>;
64
+ /**
65
+ * Active-latch lookup (see StrategyLifecycle.activeLatchBlock). Optional for the same reason;
66
+ * without it the per-signal check always runs the halt gates live.
67
+ */
68
+ activeLatchBlock?(address: string, baseline: RiskGateEvaluation, opts: {
69
+ releaseOnDayRollover: boolean;
70
+ }): Promise<RiskGateEvaluation | null>;
56
71
  };
57
72
  }
58
73
  export declare function createRiskGuard(config: RiskGuardConfig): IRiskGuard;
@@ -1 +1 @@
1
- {"version":3,"file":"risk-guard.d.ts","sourceRoot":"","sources":["../../src/runtime/risk-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAuD,SAAS,IAAI,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACvH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAe9D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,eAAe,GAAG,SAAS,GAAG,GAAG,CAAC,UAAU,CAAC,CAM5F;AAED,wBAAgB,mBAAmB,IAAI,UAAU,CAchD;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,WAAW,CAAC;IACnB,aAAa,EAAE,mBAAmB,CAAC;IACnC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE;QACjB,OAAO,CACL,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,kBAAkB,EAAE,EACjC,MAAM,EAAE,UAAU,GACjB,IAAI,CAAC;QACR;;;WAGG;QACH,UAAU,CAAC,CACT,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,EAC9B,IAAI,EAAE;YAAE,oBAAoB,EAAE,OAAO,CAAA;SAAE,GACtC,OAAO,CAAC,kBAAkB,CAAC,CAAC;KAChC,CAAC;CACH;AAkDD,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,UAAU,CAoiBnE"}
1
+ {"version":3,"file":"risk-guard.d.ts","sourceRoot":"","sources":["../../src/runtime/risk-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAmE,SAAS,IAAI,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACnI,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAsB,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIzG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAe9D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,eAAe,GAAG,SAAS,GAAG,GAAG,CAAC,UAAU,CAAC,CAM5F;AAED,wBAAgB,mBAAmB,IAAI,UAAU,CAiBhD;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,WAAW,CAAC;IACnB,aAAa,EAAE,mBAAmB,CAAC;IACnC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE;QACjB,OAAO,CACL,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,kBAAkB,EAAE,EACjC,MAAM,EAAE,UAAU,GACjB,IAAI,CAAC;QACR;;;WAGG;QACH,UAAU,CAAC,CACT,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,EAC9B,IAAI,EAAE;YAAE,oBAAoB,EAAE,OAAO,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,GACtD,OAAO,CAAC,kBAAkB,CAAC,CAAC;QAC/B;;;WAGG;QACH,gBAAgB,CAAC,CACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,kBAAkB,EAC5B,IAAI,EAAE;YAAE,oBAAoB,EAAE,OAAO,CAAA;SAAE,GACtC,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;KACvC,CAAC;CACH;AA0GD,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,UAAU,CAilBnE"}