@flighthq/log 0.5.1-next.920.da8f530 → 0.6.0

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.
package/src/log.test.ts CHANGED
@@ -1,19 +1,13 @@
1
- import { connectSignal } from '@flighthq/signals/contract';
2
- import type {
3
- BufferedLogSink,
4
- FileLogSinkDestroyOutcome,
5
- LogEntry,
6
- LogSignals,
7
- LogTransport,
8
- LogTransportDestroyOutcome,
9
- LogTransportFlushOutcome,
10
- LogTransportWriteOutcome,
11
- MemoryLogSink,
12
- } from '@flighthq/types/contract';
13
- import { EntityRuntimeKey, LogLevel } from '@flighthq/types/contract';
1
+ import { allocateEntity } from '@flighthq/entity/contract';
2
+ import { EntityRuntimeKey } from '@flighthq/entity/contract';
3
+ import { connectSignal, disconnectSignal } from '@flighthq/signals/contract';
4
+ import type { Signal, SlotId } from '@flighthq/signals/contract';
14
5
 
6
+ import { createConsoleCaptureSink } from './consoleLogSink.ts';
7
+ import type { LogState } from './log.ts';
15
8
  import {
16
9
  addLogSink,
10
+ advanceLogSink,
17
11
  beginLogGroup,
18
12
  clearLogChannelLevel,
19
13
  clearLogChannelLevels,
@@ -25,19 +19,16 @@ import {
25
19
  clearMemoryLogSink,
26
20
  createBufferedLogSink,
27
21
  createChildLogContext,
28
- createConsoleCaptureSink,
29
- createConsoleLogSink,
30
22
  createFanoutLogSink,
31
- createFileLogSink,
32
23
  createFilterLogSink,
33
24
  createJsonLogFormatter,
34
25
  createLogContext,
35
26
  createLogSpan,
27
+ createLogState,
36
28
  createMemoryLogSink,
37
29
  createRateLimitedLogSink,
38
30
  createSampledLogSink,
39
31
  createTextLogFormatter,
40
- destroyFileLogSink,
41
32
  disposeLogSink,
42
33
  enableLogSignals,
43
34
  endLogGroup,
@@ -50,6 +41,12 @@ import {
50
41
  getLogLevel,
51
42
  getLogLevelName,
52
43
  getMemoryLogSinkEntries,
44
+ initializeBufferedLogSink,
45
+ initializeLogContext,
46
+ initializeLogSpan,
47
+ initializeLogState,
48
+ initializeMemoryLogSink,
49
+ initializeRateLimitedLogSink,
53
50
  log,
54
51
  logAssert,
55
52
  logDebug,
@@ -74,55 +71,65 @@ import {
74
71
  setLogRedactionPaths,
75
72
  setLogSink,
76
73
  startLogTimer,
77
- } from './log';
74
+ } from './log.ts';
75
+ import type {
76
+ BufferedLogSink,
77
+ LogContext,
78
+ LogData,
79
+ LogEntry,
80
+ LogSignals,
81
+ LogSpan,
82
+ MemoryLogSink,
83
+ RateLimitedLogSink,
84
+ } from './types.ts';
85
+ import { LogLevel } from './types.ts';
86
+
87
+ function contextOf(channel: string | null, fields: Readonly<Record<string, unknown>> = {}): LogContext {
88
+ const context = createLogContext();
89
+ context.channel = channel;
90
+ context.fields = fields;
91
+ return context;
92
+ }
93
+
94
+ function entryOf(level: LogLevel, channel: string | null, data: LogData, timestampMs = 0): LogEntry {
95
+ return { level, channel, data, timestampMs };
96
+ }
97
+
98
+ function memoryEntries(handle: Readonly<MemoryLogSink>): LogEntry[] {
99
+ const out: LogEntry[] = [];
100
+ getMemoryLogSinkEntries(out, handle);
101
+ return out;
102
+ }
78
103
 
79
- function recordingSink(): { entries: LogEntry[]; sink: (entry: LogEntry) => void } {
104
+ function recordingSink(target: LogState = state): { entries: LogEntry[]; sink: (entry: LogEntry) => void } {
80
105
  const entries: LogEntry[] = [];
81
106
  const sink = (entry: Readonly<LogEntry>): void => {
82
107
  entries.push({ ...entry });
83
108
  };
84
- addLogSink(sink);
109
+ addLogSink(target, sink);
85
110
  return { entries, sink };
86
111
  }
87
112
 
88
- function createTestLogTransport(
89
- overrides: Partial<Pick<LogTransport, 'destroy' | 'flush' | 'write'>> = {},
90
- ): LogTransport {
91
- const defaultDestroy = async (): Promise<LogTransportDestroyOutcome> => ({ reason: 'destroyed' });
92
- const defaultFlush = async (): Promise<LogTransportFlushOutcome> => ({
93
- delivery: 'process-buffer',
94
- reason: 'drained',
95
- });
96
- const defaultWrite = (): LogTransportWriteOutcome => ({ reason: 'accepted' });
97
- return {
98
- [EntityRuntimeKey]: undefined,
99
- destroy: overrides.destroy ?? defaultDestroy,
100
- flush: overrides.flush ?? defaultFlush,
101
- write: overrides.write ?? defaultWrite,
102
- };
113
+ function spanOf(name: string, fields: Readonly<Record<string, unknown>> = {}, channel: string | null = null): LogSpan {
114
+ const span = createLogSpan(state);
115
+ span.name = name;
116
+ span.fields = fields;
117
+ span.channel = channel;
118
+ return span;
103
119
  }
104
120
 
121
+ let state: LogState;
122
+
105
123
  beforeEach(() => {
106
- clearLogGroups();
107
- clearLogOnceKeys();
108
- clearLogRedactionPaths();
109
- clearLogSerializers();
110
- clearLogSinks();
111
- clearLogChannelLevels();
112
- setLogConsoleLevel(LogLevel.Info);
113
- setLogLevel(LogLevel.Verbose);
124
+ state = createLogState();
114
125
  vi.restoreAllMocks();
115
126
  });
116
127
 
117
- afterEach(() => {
118
- clearLogSinks();
119
- });
120
-
121
128
  describe('addLogSink', () => {
122
129
  it('adds a sink that receives emitted entries', () => {
123
130
  const entries: LogEntry[] = [];
124
- addLogSink((e) => entries.push({ ...e }));
125
- log(LogLevel.Info, 'hello');
131
+ addLogSink(state, (e) => entries.push({ ...e }));
132
+ log(state, 0, LogLevel.Info, 'hello');
126
133
  expect(entries).toHaveLength(1);
127
134
  });
128
135
 
@@ -131,73 +138,126 @@ describe('addLogSink', () => {
131
138
  const sink = (e: Readonly<LogEntry>): void => {
132
139
  entries.push({ ...e });
133
140
  };
134
- addLogSink(sink);
135
- addLogSink(sink);
136
- log(LogLevel.Info, 'x');
141
+ addLogSink(state, sink);
142
+ addLogSink(state, sink);
143
+ log(state, 0, LogLevel.Info, 'x');
137
144
  expect(entries).toHaveLength(1);
138
145
  });
146
+
147
+ it('isolates sinks and once keys between separate log states', () => {
148
+ const other = createLogState();
149
+ const { entries } = recordingSink();
150
+ const { entries: otherEntries } = recordingSink(other);
151
+
152
+ log(state, 0, LogLevel.Info, 'mine');
153
+ expect(logOnce(state, 0, 'shared-key', LogLevel.Warn, 'first')).toBe(true);
154
+ expect(logOnce(other, 0, 'shared-key', LogLevel.Warn, 'other-first')).toBe(true);
155
+
156
+ expect(entries.map((entry) => entry.data)).toEqual(['mine', 'first']);
157
+ expect(otherEntries.map((entry) => entry.data)).toEqual(['other-first']);
158
+ });
139
159
  });
140
160
 
141
- describe('beginLogGroup', () => {
142
- afterEach(() => clearLogGroups());
161
+ describe('advanceLogSink', () => {
162
+ it('only starts the interval on the first advance', () => {
163
+ const forwarded: LogEntry[] = [];
164
+ const handle = createBufferedLogSink((e) => forwarded.push({ ...e }), { intervalMs: 100 });
165
+ handle.sink(entryOf(LogLevel.Info, null, 'queued'));
143
166
 
167
+ advanceLogSink(handle, 1000);
168
+
169
+ expect(forwarded).toHaveLength(0);
170
+ });
171
+
172
+ it('flushes once the interval has elapsed since the last flush', () => {
173
+ const forwarded: LogEntry[] = [];
174
+ const handle = createBufferedLogSink((e) => forwarded.push({ ...e }), { intervalMs: 100 });
175
+ advanceLogSink(handle, 0);
176
+ handle.sink(entryOf(LogLevel.Info, null, 'queued'));
177
+
178
+ advanceLogSink(handle, 99);
179
+ expect(forwarded).toHaveLength(0);
180
+ advanceLogSink(handle, 100);
181
+ expect(forwarded.map((entry) => entry.data)).toEqual(['queued']);
182
+ });
183
+
184
+ it('measures the next interval from the last flush', () => {
185
+ const forwarded: LogEntry[] = [];
186
+ const handle = createBufferedLogSink((e) => forwarded.push({ ...e }), { intervalMs: 100 });
187
+ advanceLogSink(handle, 0);
188
+ advanceLogSink(handle, 100);
189
+ handle.sink(entryOf(LogLevel.Info, null, 'later'));
190
+
191
+ advanceLogSink(handle, 150);
192
+ expect(forwarded).toHaveLength(0);
193
+ advanceLogSink(handle, 200);
194
+ expect(forwarded).toHaveLength(1);
195
+ });
196
+
197
+ it('does nothing for an unknown handle', () => {
198
+ const unknown: BufferedLogSink = { [EntityRuntimeKey]: undefined, sink: () => {} };
199
+
200
+ expect(() => advanceLogSink(unknown, 0)).not.toThrow();
201
+ });
202
+ });
203
+
204
+ describe('beginLogGroup', () => {
144
205
  it('emits a Debug group-begin entry and increments nesting depth', () => {
145
206
  const { entries } = recordingSink();
146
- beginLogGroup('setup');
207
+ beginLogGroup(state, 5, 'setup');
147
208
  expect(entries).toHaveLength(1);
148
209
  expect(entries[0].level).toBe(LogLevel.Debug);
210
+ expect(entries[0].timestampMs).toBe(5);
149
211
  expect(entries[0].data).toMatchObject({ group: 'begin', depth: 1 });
150
212
  });
151
213
 
152
214
  it('nests: second beginLogGroup produces depth 2', () => {
153
215
  const { entries } = recordingSink();
154
- beginLogGroup('outer');
155
- beginLogGroup('inner');
216
+ beginLogGroup(state, 0, 'outer');
217
+ beginLogGroup(state, 0, 'inner');
156
218
  expect(entries[1].data).toMatchObject({ depth: 2 });
157
219
  });
158
220
 
159
221
  it('tracks depth without emitting when Debug is suppressed', () => {
160
222
  const { entries } = recordingSink();
161
- setLogLevel(LogLevel.Error);
223
+ setLogLevel(state, LogLevel.Error);
162
224
 
163
- beginLogGroup('suppressed');
225
+ beginLogGroup(state, 0, 'suppressed');
164
226
 
165
227
  expect(entries).toHaveLength(0);
166
- clearLogGroups();
228
+ expect(state.groupDepth).toBe(1);
167
229
  });
168
230
  });
169
231
 
170
232
  describe('clearLogChannelLevel', () => {
171
233
  it('removes only the named channel override', () => {
172
- setLogChannelLevel('render', LogLevel.Error);
173
- setLogChannelLevel('input', LogLevel.Warn);
234
+ setLogChannelLevel(state, 'render', LogLevel.Error);
235
+ setLogChannelLevel(state, 'input', LogLevel.Warn);
174
236
 
175
- clearLogChannelLevel('render');
237
+ clearLogChannelLevel(state, 'render');
176
238
 
177
- expect(getLogChannelLevel('render')).toBeNull();
178
- expect(getLogChannelLevel('input')).toBe(LogLevel.Warn);
239
+ expect(getLogChannelLevel(state, 'render')).toBeNull();
240
+ expect(getLogChannelLevel(state, 'input')).toBe(LogLevel.Warn);
179
241
  });
180
242
  });
181
243
 
182
244
  describe('clearLogChannelLevels', () => {
183
245
  it('removes all per-channel level overrides', () => {
184
- setLogChannelLevel('render', LogLevel.Error);
185
- clearLogChannelLevels();
186
- expect(getLogChannelLevel('render')).toBeNull();
246
+ setLogChannelLevel(state, 'render', LogLevel.Error);
247
+ clearLogChannelLevels(state);
248
+ expect(getLogChannelLevel(state, 'render')).toBeNull();
187
249
  });
188
250
  });
189
251
 
190
252
  describe('clearLogGroups', () => {
191
- afterEach(() => clearLogGroups());
192
-
193
253
  it('resets group nesting depth to zero without emitting', () => {
194
254
  const { entries } = recordingSink();
195
- beginLogGroup('a');
196
- beginLogGroup('b');
255
+ beginLogGroup(state, 0, 'a');
256
+ beginLogGroup(state, 0, 'b');
197
257
  entries.length = 0;
198
- clearLogGroups();
258
+ clearLogGroups(state);
199
259
  // After clearLogGroups, endLogGroup should be a no-op (depth is 0)
200
- endLogGroup();
260
+ endLogGroup(state, 0);
201
261
  expect(entries).toHaveLength(0);
202
262
  });
203
263
  });
@@ -205,10 +265,10 @@ describe('clearLogGroups', () => {
205
265
  describe('clearLogOnceKeys', () => {
206
266
  it('allows a previously consumed key to fire again', () => {
207
267
  const { entries } = recordingSink();
208
- logOnce('once-clear-test', LogLevel.Warn, 'first');
268
+ logOnce(state, 0, 'once-clear-test', LogLevel.Warn, 'first');
209
269
  expect(entries).toHaveLength(1);
210
- clearLogOnceKeys();
211
- logOnce('once-clear-test', LogLevel.Warn, 'second');
270
+ clearLogOnceKeys(state);
271
+ logOnce(state, 0, 'once-clear-test', LogLevel.Warn, 'second');
212
272
  expect(entries).toHaveLength(2);
213
273
  expect(entries[1].data).toBe('second');
214
274
  });
@@ -216,22 +276,20 @@ describe('clearLogOnceKeys', () => {
216
276
 
217
277
  describe('clearLogRedactionPaths', () => {
218
278
  it('removes all redaction paths so fields are no longer redacted', () => {
219
- setLogRedactionPaths(['token']);
220
- clearLogRedactionPaths();
221
- const fmt = createJsonLogFormatter();
222
- const entry: LogEntry = { level: LogLevel.Info, channel: null, data: { token: 'secret' } };
223
- const result = JSON.parse(fmt(entry));
279
+ setLogRedactionPaths(state, ['token']);
280
+ clearLogRedactionPaths(state);
281
+ const fmt = createJsonLogFormatter(state);
282
+ const result = JSON.parse(fmt(entryOf(LogLevel.Info, null, { token: 'secret' })));
224
283
  expect(result.data.token).toBe('secret');
225
284
  });
226
285
  });
227
286
 
228
287
  describe('clearLogSerializers', () => {
229
288
  it('removes all serializer registrations', () => {
230
- registerLogSerializer('acme.Foo', () => ({ serialized: true }));
231
- clearLogSerializers();
232
- const fmt = createJsonLogFormatter();
233
- const entry: LogEntry = { level: LogLevel.Info, channel: null, data: { obj: { __kind: 'acme.Foo', x: 1 } } };
234
- const result = JSON.parse(fmt(entry));
289
+ registerLogSerializer(state, 'acme.Foo', () => ({ serialized: true }));
290
+ clearLogSerializers(state);
291
+ const fmt = createJsonLogFormatter(state);
292
+ const result = JSON.parse(fmt(entryOf(LogLevel.Info, null, { obj: { __kind: 'acme.Foo', x: 1 } })));
235
293
  // Without serializer the value should pass through as-is
236
294
  expect(result.data.obj.__kind).toBe('acme.Foo');
237
295
  });
@@ -240,9 +298,9 @@ describe('clearLogSerializers', () => {
240
298
  describe('clearLogSinks', () => {
241
299
  it('removes all sinks so subsequent emit calls are no-ops', () => {
242
300
  const entries: LogEntry[] = [];
243
- addLogSink((e) => entries.push({ ...e }));
244
- clearLogSinks();
245
- log(LogLevel.Info, 'x');
301
+ addLogSink(state, (e) => entries.push({ ...e }));
302
+ clearLogSinks(state);
303
+ log(state, 0, LogLevel.Info, 'x');
246
304
  expect(entries).toHaveLength(0);
247
305
  });
248
306
  });
@@ -250,10 +308,20 @@ describe('clearLogSinks', () => {
250
308
  describe('clearMemoryLogSink', () => {
251
309
  it('empties the captured entries', () => {
252
310
  const handle = createMemoryLogSink(10);
253
- addLogSink(handle.sink);
254
- log(LogLevel.Info, 'a');
311
+ addLogSink(state, handle.sink);
312
+ log(state, 0, LogLevel.Info, 'a');
313
+ clearMemoryLogSink(handle);
314
+ expect(memoryEntries(handle)).toHaveLength(0);
315
+ });
316
+
317
+ it('restarts the ring at the oldest slot after clearing a wrapped buffer', () => {
318
+ const handle = createMemoryLogSink(2);
319
+ addLogSink(state, handle.sink);
320
+ for (const data of ['a', 'b', 'c']) log(state, 0, LogLevel.Info, data);
255
321
  clearMemoryLogSink(handle);
256
- expect(getMemoryLogSinkEntries(handle)).toHaveLength(0);
322
+ log(state, 0, LogLevel.Info, 'd');
323
+ log(state, 0, LogLevel.Info, 'e');
324
+ expect(memoryEntries(handle).map((entry) => entry.data)).toEqual(['d', 'e']);
257
325
  });
258
326
 
259
327
  it('does nothing for an unknown handle', () => {
@@ -265,36 +333,26 @@ describe('clearMemoryLogSink', () => {
265
333
 
266
334
  describe('createBufferedLogSink', () => {
267
335
  it('uses the default size and interval options', () => {
268
- vi.useFakeTimers();
269
- try {
270
- const forwarded: LogEntry[] = [];
271
- const handle = createBufferedLogSink((entry) => forwarded.push({ ...entry }));
272
- handle.sink({ channel: null, data: 'queued', level: LogLevel.Info });
273
-
274
- expect(forwarded).toHaveLength(0);
275
- flushLogSink(handle);
276
- expect(forwarded).toHaveLength(1);
277
- disposeLogSink(handle);
278
- } finally {
279
- vi.useRealTimers();
280
- }
281
- });
282
-
283
- it('works without an interval implementation', () => {
284
- const originalSetInterval = globalThis.setInterval;
285
- let handle: BufferedLogSink;
286
- Object.defineProperty(globalThis, 'setInterval', { configurable: true, value: undefined, writable: true });
287
- try {
288
- handle = createBufferedLogSink(() => {}, { intervalMs: 1, size: 1 });
289
- } finally {
290
- Object.defineProperty(globalThis, 'setInterval', {
291
- configurable: true,
292
- value: originalSetInterval,
293
- writable: true,
294
- });
295
- }
296
-
297
- expect(() => disposeLogSink(handle!)).not.toThrow();
336
+ const forwarded: LogEntry[] = [];
337
+ const handle = createBufferedLogSink((entry) => forwarded.push({ ...entry }));
338
+ for (let i = 0; i < 99; i++) handle.sink(entryOf(LogLevel.Info, null, `queued-${i}`));
339
+ advanceLogSink(handle, 0);
340
+ advanceLogSink(handle, 999);
341
+
342
+ expect(forwarded).toHaveLength(0);
343
+ advanceLogSink(handle, 1000);
344
+ expect(forwarded).toHaveLength(99);
345
+ handle.sink(entryOf(LogLevel.Info, null, 'below-size'));
346
+ expect(forwarded).toHaveLength(99);
347
+ });
348
+
349
+ it('never schedules an interval timer', () => {
350
+ const setIntervalSpy = vi.spyOn(globalThis, 'setInterval');
351
+
352
+ const handle = createBufferedLogSink(() => {}, { intervalMs: 1, size: 1 });
353
+ disposeLogSink(handle);
354
+
355
+ expect(setIntervalSpy).not.toHaveBeenCalled();
298
356
  });
299
357
 
300
358
  it('does nothing when an empty buffer is flushed', () => {
@@ -309,8 +367,8 @@ describe('createBufferedLogSink', () => {
309
367
  it('does not forward entries until flushed', () => {
310
368
  const forwarded: LogEntry[] = [];
311
369
  const handle = createBufferedLogSink((e) => forwarded.push({ ...e }), { size: 100, intervalMs: 0 });
312
- addLogSink(handle.sink);
313
- log(LogLevel.Info, 'queued');
370
+ addLogSink(state, handle.sink);
371
+ log(state, 0, LogLevel.Info, 'queued');
314
372
  expect(forwarded).toHaveLength(0);
315
373
  flushLogSink(handle);
316
374
  expect(forwarded).toHaveLength(1);
@@ -319,17 +377,29 @@ describe('createBufferedLogSink', () => {
319
377
  it('auto-flushes when buffer reaches size', () => {
320
378
  const forwarded: LogEntry[] = [];
321
379
  const handle = createBufferedLogSink((e) => forwarded.push({ ...e }), { size: 2, intervalMs: 0 });
322
- addLogSink(handle.sink);
323
- log(LogLevel.Info, 'a');
324
- log(LogLevel.Info, 'b');
380
+ addLogSink(state, handle.sink);
381
+ log(state, 0, LogLevel.Info, 'a');
382
+ log(state, 0, LogLevel.Info, 'b');
325
383
  expect(forwarded).toHaveLength(2);
326
384
  });
327
385
 
328
- it('disposeLogSink flushes and stops future auto-flush', () => {
386
+ it('keeps its own copy of each queued entry', () => {
387
+ const forwarded: LogEntry[] = [];
388
+ const handle = createBufferedLogSink((e) => forwarded.push({ ...e }), { size: 100 });
389
+ const entry = entryOf(LogLevel.Info, null, 'original', 7);
390
+ handle.sink(entry);
391
+ entry.data = 'rewritten';
392
+
393
+ flushLogSink(handle);
394
+
395
+ expect(forwarded[0]).toEqual(entryOf(LogLevel.Info, null, 'original', 7));
396
+ });
397
+
398
+ it('disposeLogSink flushes pending entries', () => {
329
399
  const forwarded: LogEntry[] = [];
330
400
  const handle = createBufferedLogSink((e) => forwarded.push({ ...e }), { size: 100, intervalMs: 0 });
331
- addLogSink(handle.sink);
332
- log(LogLevel.Info, 'pending');
401
+ addLogSink(state, handle.sink);
402
+ log(state, 0, LogLevel.Info, 'pending');
333
403
  disposeLogSink(handle);
334
404
  expect(forwarded).toHaveLength(1);
335
405
  });
@@ -337,112 +407,26 @@ describe('createBufferedLogSink', () => {
337
407
 
338
408
  describe('createChildLogContext', () => {
339
409
  it('merges parent and child fields (child wins)', () => {
340
- const parent = createLogContext('chan', { a: 1, b: 2 });
410
+ const parent = contextOf('chan', { a: 1, b: 2 });
341
411
  const child = createChildLogContext(parent, { b: 99, c: 3 });
342
412
  expect(child.fields).toEqual({ a: 1, b: 99, c: 3 });
343
413
  });
344
414
 
345
415
  it('inherits parent channel when no override given', () => {
346
- const parent = createLogContext('parent', {});
416
+ const parent = contextOf('parent');
347
417
  const child = createChildLogContext(parent, {});
348
418
  expect(child.channel).toBe('parent');
349
419
  });
350
420
 
351
421
  it('overrides channel when provided', () => {
352
- const parent = createLogContext('parent', {});
422
+ const parent = contextOf('parent');
353
423
  const child = createChildLogContext(parent, {}, 'child');
354
424
  expect(child.channel).toBe('child');
355
425
  });
356
- });
357
-
358
- describe('createConsoleCaptureSink', () => {
359
- it('records every level as a tagged JSON envelope on console.debug', () => {
360
- const debug = vi.spyOn(console, 'debug').mockImplementation(() => {});
361
- setLogConsoleLevel(LogLevel.None);
362
- setLogSink(createConsoleCaptureSink());
363
- log(LogLevel.Verbose, { n: 1 }, 'batch');
364
- expect(debug).toHaveBeenCalledTimes(1);
365
- const parsed = JSON.parse((debug.mock.calls[0] as string[])[0]);
366
- expect(parsed).toMatchObject({ __flight: true, level: 'verbose', channel: 'batch', data: { n: 1 } });
367
- });
368
-
369
- it('also prints a human line only for levels at or above the console threshold', () => {
370
- vi.spyOn(console, 'debug').mockImplementation(() => {});
371
- const info = vi.spyOn(console, 'info').mockImplementation(() => {});
372
- const consoleLog = vi.spyOn(console, 'log').mockImplementation(() => {});
373
- setLogConsoleLevel(LogLevel.Info);
374
- setLogSink(createConsoleCaptureSink());
375
- log(LogLevel.Info, 'shown');
376
- log(LogLevel.Verbose, 'hidden');
377
- expect(info).toHaveBeenCalledTimes(1);
378
- expect(consoleLog).not.toHaveBeenCalled();
379
- });
380
-
381
- it('wraps a string payload as { msg } in the envelope', () => {
382
- const debug = vi.spyOn(console, 'debug').mockImplementation(() => {});
383
- setLogSink(createConsoleCaptureSink());
384
- log(LogLevel.Error, 'boom');
385
- expect(JSON.parse((debug.mock.calls[0] as string[])[0]).data).toEqual({ msg: 'boom' });
386
- });
387
-
388
- it('accepts a custom formatter', () => {
389
- const debug = vi.spyOn(console, 'debug').mockImplementation(() => {});
390
- const customFormatter = vi.fn(() => 'custom-line');
391
- setLogSink(createConsoleCaptureSink({ formatter: customFormatter }));
392
- log(LogLevel.Info, 'x');
393
- expect(customFormatter).toHaveBeenCalledTimes(1);
394
- expect(debug).toHaveBeenCalledWith('custom-line');
395
- });
396
-
397
- it('prints a channel prefix with structured human-readable data', () => {
398
- vi.spyOn(console, 'debug').mockImplementation(() => {});
399
- const info = vi.spyOn(console, 'info').mockImplementation(() => {});
400
- setLogConsoleLevel(LogLevel.Info);
401
- setLogSink(createConsoleCaptureSink());
402
-
403
- log(LogLevel.Info, { frame: 7 }, 'render');
404
-
405
- expect(info).toHaveBeenCalledWith('[render]', { frame: 7 });
406
- });
407
-
408
- it('does nothing when the console is unavailable', () => {
409
- const captureSink = createConsoleCaptureSink();
410
- const textSink = createConsoleLogSink();
411
- const originalConsole = globalThis.console;
412
- let threw = false;
413
- Object.defineProperty(globalThis, 'console', { configurable: true, value: undefined, writable: true });
414
- try {
415
- captureSink({ channel: null, data: 'capture', level: LogLevel.Info });
416
- textSink({ channel: null, data: 'text', level: LogLevel.Info });
417
- } catch {
418
- threw = true;
419
- } finally {
420
- Object.defineProperty(globalThis, 'console', {
421
- configurable: true,
422
- value: originalConsole,
423
- writable: true,
424
- });
425
- }
426
-
427
- expect(threw).toBe(false);
428
- });
429
- });
430
-
431
- describe('createConsoleLogSink', () => {
432
- it('writes the formatted entry to the console method matching its level', () => {
433
- const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
434
- const sink = createConsoleLogSink({ formatter: () => 'formatted warning' });
435
- sink({ channel: 'render', data: 'ignored', level: LogLevel.Warn });
436
- expect(warn).toHaveBeenCalledWith('formatted warning');
437
- });
438
-
439
- it('uses a level-prefixed text formatter by default', () => {
440
- const error = vi.spyOn(console, 'error').mockImplementation(() => {});
441
- const sink = createConsoleLogSink();
442
426
 
443
- sink({ channel: null, data: 'failed', level: LogLevel.Error });
444
-
445
- expect(error).toHaveBeenCalledWith('error [flight] failed');
427
+ it('overrides the channel with an explicit null', () => {
428
+ const child = createChildLogContext(contextOf('parent'), {}, null);
429
+ expect(child.channel).toBeNull();
446
430
  });
447
431
  });
448
432
 
@@ -450,87 +434,22 @@ describe('createFanoutLogSink', () => {
450
434
  it('forwards each entry to all component sinks', () => {
451
435
  const a: LogEntry[] = [];
452
436
  const b: LogEntry[] = [];
453
- const fanout = createFanoutLogSink(
454
- (e) => a.push({ ...e }),
455
- (e) => b.push({ ...e }),
456
- );
457
- addLogSink(fanout);
458
- log(LogLevel.Info, 'hello');
437
+ const fanout = createFanoutLogSink([(e) => a.push({ ...e }), (e) => b.push({ ...e })]);
438
+ addLogSink(state, fanout);
439
+ log(state, 0, LogLevel.Info, 'hello');
459
440
  expect(a).toHaveLength(1);
460
441
  expect(b).toHaveLength(1);
461
442
  });
462
- });
463
-
464
- describe('createFileLogSink', () => {
465
- it.each<LogTransportWriteOutcome>([
466
- { reason: 'accepted' },
467
- { reason: 'backpressure', retryAfterMs: 25 },
468
- { message: 'disk full', reason: 'operation-failed' },
469
- { reason: 'destroyed' },
470
- ])('offers one complete formatted line when admission reports $reason', (writeOutcome) => {
471
- const lines: string[] = [];
472
- const transport = createTestLogTransport({
473
- write(line) {
474
- lines.push(line);
475
- return writeOutcome;
476
- },
477
- });
478
- const handle = createFileLogSink(transport);
479
- addLogSink(handle.sink);
480
- log(LogLevel.Info, 'file-entry');
481
- expect(lines).toHaveLength(1);
482
- const parsed = JSON.parse(lines[0]);
483
- expect(parsed).toMatchObject({ __flight: true, level: 'info', data: { msg: 'file-entry' } });
484
- });
485
443
 
486
- it('creates an Entity handle', () => {
487
- const handle = createFileLogSink(createTestLogTransport());
488
-
489
- expect(EntityRuntimeKey in handle).toBe(true);
490
- expect(handle[EntityRuntimeKey]).toBeUndefined();
491
- });
492
-
493
- it('accepts a custom formatter', () => {
494
- const lines: string[] = [];
495
- const transport = createTestLogTransport({
496
- write(line) {
497
- lines.push(line);
498
- return { reason: 'accepted' };
499
- },
500
- });
501
- const handle = createFileLogSink(transport, { formatter: () => 'custom' });
502
- addLogSink(handle.sink);
503
- log(LogLevel.Info, 'x');
504
- expect(lines[0]).toBe('custom\n');
505
- });
506
-
507
- it('pins each handle to its injected transport', () => {
508
- const firstLines: string[] = [];
509
- const secondLines: string[] = [];
510
- const first = createFileLogSink(
511
- createTestLogTransport({
512
- write(line) {
513
- firstLines.push(line);
514
- return { reason: 'accepted' };
515
- },
516
- }),
517
- { formatter: () => 'first' },
518
- );
519
- const second = createFileLogSink(
520
- createTestLogTransport({
521
- write(line) {
522
- secondLines.push(line);
523
- return { reason: 'accepted' };
524
- },
525
- }),
526
- { formatter: () => 'second' },
527
- );
444
+ it('copies the sink list so later edits to the array do not change the fan-out', () => {
445
+ const a: LogEntry[] = [];
446
+ const sinks = [(e: Readonly<LogEntry>): void => void a.push({ ...e })];
447
+ const fanout = createFanoutLogSink(sinks);
448
+ sinks.length = 0;
528
449
 
529
- first.sink({ channel: null, data: 'entry', level: LogLevel.Info });
530
- second.sink({ channel: null, data: 'entry', level: LogLevel.Info });
450
+ fanout(entryOf(LogLevel.Info, null, 'still-forwarded'));
531
451
 
532
- expect(firstLines).toEqual(['first\n']);
533
- expect(secondLines).toEqual(['second\n']);
452
+ expect(a).toHaveLength(1);
534
453
  });
535
454
  });
536
455
 
@@ -541,9 +460,9 @@ describe('createFilterLogSink', () => {
541
460
  (e) => entries.push({ ...e }),
542
461
  (e) => e.level === LogLevel.Error,
543
462
  );
544
- addLogSink(filtered);
545
- log(LogLevel.Info, 'skip');
546
- log(LogLevel.Error, 'keep');
463
+ addLogSink(state, filtered);
464
+ log(state, 0, LogLevel.Info, 'skip');
465
+ log(state, 0, LogLevel.Error, 'keep');
547
466
  expect(entries).toHaveLength(1);
548
467
  expect(entries[0].level).toBe(LogLevel.Error);
549
468
  });
@@ -551,84 +470,109 @@ describe('createFilterLogSink', () => {
551
470
 
552
471
  describe('createJsonLogFormatter', () => {
553
472
  it('produces a __flight JSON envelope', () => {
554
- const fmt = createJsonLogFormatter();
555
- const entry: LogEntry = { level: LogLevel.Info, channel: 'test', data: 'msg' };
556
- const result = JSON.parse(fmt(entry));
473
+ const fmt = createJsonLogFormatter(state);
474
+ const result = JSON.parse(fmt(entryOf(LogLevel.Info, 'test', 'msg')));
557
475
  expect(result).toMatchObject({ __flight: true, level: 'info', channel: 'test', data: { msg: 'msg' } });
558
476
  });
559
477
 
478
+ it("uses the entry's own timestamp as t", () => {
479
+ const fmt = createJsonLogFormatter(state);
480
+ expect(JSON.parse(fmt(entryOf(LogLevel.Info, null, 'msg', 42.5))).t).toBe(42.5);
481
+ });
482
+
560
483
  it('applies registered serializers to values with matching __kind', () => {
561
- registerLogSerializer('acme.Widget', (v) => ({ serialized: true, id: (v as { id: number }).id }));
562
- const fmt = createJsonLogFormatter();
563
- const entry: LogEntry = {
564
- level: LogLevel.Info,
565
- channel: null,
566
- data: { widget: { __kind: 'acme.Widget', id: 42 } },
567
- };
568
- const result = JSON.parse(fmt(entry));
484
+ registerLogSerializer(state, 'acme.Widget', (v) => ({ serialized: true, id: (v as { id: number }).id }));
485
+ const fmt = createJsonLogFormatter(state);
486
+ const result = JSON.parse(fmt(entryOf(LogLevel.Info, null, { widget: { __kind: 'acme.Widget', id: 42 } })));
569
487
  expect(result.data.widget).toEqual({ serialized: true, id: 42 });
570
488
  });
571
489
 
572
490
  it('applies redaction paths to nested fields', () => {
573
- setLogRedactionPaths(['credentials.token', 'password']);
574
- const fmt = createJsonLogFormatter();
575
- const entry: LogEntry = {
576
- level: LogLevel.Info,
577
- channel: null,
578
- data: { credentials: { token: 'secret', user: 'alice' }, password: 'pw' },
579
- };
580
- const result = JSON.parse(fmt(entry));
491
+ setLogRedactionPaths(state, ['credentials.token', 'password']);
492
+ const fmt = createJsonLogFormatter(state);
493
+ const result = JSON.parse(
494
+ fmt(entryOf(LogLevel.Info, null, { credentials: { token: 'secret', user: 'alice' }, password: 'pw' })),
495
+ );
581
496
  expect(result.data.credentials.token).toBe('[REDACTED]');
582
497
  expect(result.data.credentials.user).toBe('alice');
583
498
  expect(result.data.password).toBe('[REDACTED]');
584
499
  });
500
+
501
+ it('reads redaction and serializers from its state at format time', () => {
502
+ const fmt = createJsonLogFormatter(state);
503
+ setLogRedactionPaths(state, ['token']);
504
+
505
+ const result = JSON.parse(fmt(entryOf(LogLevel.Info, null, { token: 'secret' })));
506
+
507
+ expect(result.data.token).toBe('[REDACTED]');
508
+ });
585
509
  });
586
510
 
587
511
  describe('createLogContext', () => {
588
- it('creates a context with the given channel and fields', () => {
589
- const ctx = createLogContext('render', { version: 1 });
590
- expect(ctx.channel).toBe('render');
591
- expect(ctx.fields).toEqual({ version: 1 });
512
+ it('creates an empty context to assign', () => {
513
+ const ctx = createLogContext();
514
+ expect(ctx.channel).toBeNull();
515
+ expect(ctx.fields).toEqual({});
592
516
  });
593
517
 
594
- it('defaults fields to empty object', () => {
595
- const ctx = createLogContext('ch');
596
- expect(ctx.fields).toEqual({});
518
+ it('carries an assigned channel and fields into contextual emits', () => {
519
+ const { entries } = recordingSink();
520
+ const ctx = contextOf('render', { version: 1 });
521
+ logWith(state, 0, ctx, LogLevel.Info, 'x');
522
+ expect(entries[0]).toMatchObject({ channel: 'render', data: { msg: 'x', version: 1 } });
597
523
  });
598
524
  });
599
525
 
600
526
  describe('createLogSpan', () => {
601
- it('creates a LogSpan plain value with the given name, fields, and channel', () => {
602
- const span = createLogSpan('render-frame', { frame: 1 }, 'perf');
603
- expect(span.name).toBe('render-frame');
604
- expect(span.fields).toEqual({ frame: 1 });
605
- expect(span.channel).toBe('perf');
527
+ it('creates an empty span with the next id from the state', () => {
528
+ const first = createLogSpan(state);
529
+ const second = createLogSpan(state);
530
+ expect(first.name).toBe('');
531
+ expect(first.fields).toEqual({});
532
+ expect(first.channel).toBeNull();
533
+ expect(first.id).toBe(1);
534
+ expect(second.id).toBe(2);
606
535
  });
607
536
 
608
- it('defaults fields to empty object and channel to null', () => {
609
- const span = createLogSpan('op');
610
- expect(span.fields).toEqual({});
611
- expect(span.channel).toBeNull();
537
+ it('allocates ids per state', () => {
538
+ createLogSpan(state);
539
+ expect(createLogSpan(createLogState()).id).toBe(1);
540
+ });
541
+ });
542
+
543
+ describe('createLogState', () => {
544
+ it('starts with no sinks, Verbose emit level, and Info console level', () => {
545
+ const fresh = createLogState();
546
+ expect(fresh.sinks).toEqual([]);
547
+ expect(getLogLevel(fresh)).toBe(LogLevel.Verbose);
548
+ expect(getLogConsoleLevel(fresh)).toBe(LogLevel.Info);
549
+ expect(fresh.groupDepth).toBe(0);
550
+ expect(fresh.signals).toBeNull();
551
+ expect(fresh.nextSpanId).toBe(1);
552
+ });
553
+
554
+ it('creates an Entity', () => {
555
+ expect(EntityRuntimeKey in createLogState()).toBe(true);
612
556
  });
613
557
  });
614
558
 
615
559
  describe('createMemoryLogSink', () => {
616
560
  it('captures entries up to capacity', () => {
617
561
  const handle = createMemoryLogSink(3);
618
- addLogSink(handle.sink);
619
- log(LogLevel.Info, 'a');
620
- log(LogLevel.Info, 'b');
621
- log(LogLevel.Info, 'c');
622
- expect(getMemoryLogSinkEntries(handle)).toHaveLength(3);
562
+ addLogSink(state, handle.sink);
563
+ log(state, 0, LogLevel.Info, 'a');
564
+ log(state, 0, LogLevel.Info, 'b');
565
+ log(state, 0, LogLevel.Info, 'c');
566
+ expect(memoryEntries(handle)).toHaveLength(3);
623
567
  });
624
568
 
625
569
  it('overwrites oldest entries when capacity is exceeded (ring buffer)', () => {
626
570
  const handle = createMemoryLogSink(2);
627
- addLogSink(handle.sink);
628
- log(LogLevel.Info, 'first');
629
- log(LogLevel.Info, 'second');
630
- log(LogLevel.Info, 'third');
631
- const entries = getMemoryLogSinkEntries(handle);
571
+ addLogSink(state, handle.sink);
572
+ log(state, 0, LogLevel.Info, 'first');
573
+ log(state, 0, LogLevel.Info, 'second');
574
+ log(state, 0, LogLevel.Info, 'third');
575
+ const entries = memoryEntries(handle);
632
576
  expect(entries).toHaveLength(2);
633
577
  expect(entries[0].data).toBe('second');
634
578
  expect(entries[1].data).toBe('third');
@@ -636,10 +580,17 @@ describe('createMemoryLogSink', () => {
636
580
 
637
581
  it('returns entries oldest-first after capacity exceeded', () => {
638
582
  const handle = createMemoryLogSink(3);
639
- addLogSink(handle.sink);
640
- for (let i = 0; i < 5; i++) log(LogLevel.Info, `msg${i}`);
641
- const entries = getMemoryLogSinkEntries(handle);
642
- expect(entries.map((e) => e.data)).toEqual(['msg2', 'msg3', 'msg4']);
583
+ addLogSink(state, handle.sink);
584
+ for (let i = 0; i < 5; i++) log(state, 0, LogLevel.Info, `msg${i}`);
585
+ expect(memoryEntries(handle).map((e) => e.data)).toEqual(['msg2', 'msg3', 'msg4']);
586
+ });
587
+
588
+ it('stores the timestamp and its own copy of each entry', () => {
589
+ const handle = createMemoryLogSink(1);
590
+ const entry = entryOf(LogLevel.Warn, 'ch', 'kept', 12);
591
+ handle.sink(entry);
592
+ entry.data = 'rewritten';
593
+ expect(memoryEntries(handle)).toEqual([entryOf(LogLevel.Warn, 'ch', 'kept', 12)]);
643
594
  });
644
595
  });
645
596
 
@@ -647,10 +598,10 @@ describe('createRateLimitedLogSink', () => {
647
598
  it('limits entries per interval', () => {
648
599
  const forwarded: LogEntry[] = [];
649
600
  const handle = createRateLimitedLogSink((e) => forwarded.push({ ...e }), { maxPerInterval: 2, intervalMs: 10000 });
650
- addLogSink(handle.sink);
651
- log(LogLevel.Info, 'a');
652
- log(LogLevel.Info, 'b');
653
- log(LogLevel.Info, 'c'); // should be rate-limited
601
+ addLogSink(state, handle.sink);
602
+ log(state, 0, LogLevel.Info, 'a');
603
+ log(state, 0, LogLevel.Info, 'b');
604
+ log(state, 0, LogLevel.Info, 'c'); // should be rate-limited
654
605
  expect(forwarded).toHaveLength(2);
655
606
  });
656
607
 
@@ -661,34 +612,28 @@ describe('createRateLimitedLogSink', () => {
661
612
  maxPerInterval: 1,
662
613
  intervalMs: 10000,
663
614
  });
664
- addLogSink(handle.sink);
665
- log(LogLevel.Info, 'a', 'ch1');
666
- log(LogLevel.Info, 'b', 'ch1'); // rate-limited for ch1
667
- log(LogLevel.Info, 'c', 'ch2'); // allowed — different channel
615
+ addLogSink(state, handle.sink);
616
+ log(state, 0, LogLevel.Info, 'a', 'ch1');
617
+ log(state, 0, LogLevel.Info, 'b', 'ch1'); // rate-limited for ch1
618
+ log(state, 0, LogLevel.Info, 'c', 'ch2'); // allowed — different channel
668
619
  expect(forwarded).toHaveLength(2);
669
620
  expect(forwarded[0].channel).toBe('ch1');
670
621
  expect(forwarded[1].channel).toBe('ch2');
671
622
  });
672
623
 
673
- it('resets its budget after the interval elapses', () => {
674
- vi.useFakeTimers();
675
- try {
676
- const forwarded: LogEntry[] = [];
677
- const handle = createRateLimitedLogSink((entry) => forwarded.push({ ...entry }), {
678
- intervalMs: 100,
679
- maxPerInterval: 1,
680
- });
681
- addLogSink(handle.sink);
682
- log(LogLevel.Info, 'first');
683
- log(LogLevel.Info, 'suppressed');
684
- vi.advanceTimersByTime(100);
624
+ it('resets its budget once entry timestamps cross the interval', () => {
625
+ const forwarded: LogEntry[] = [];
626
+ const handle = createRateLimitedLogSink((entry) => forwarded.push({ ...entry }), {
627
+ intervalMs: 100,
628
+ maxPerInterval: 1,
629
+ });
630
+ addLogSink(state, handle.sink);
631
+ log(state, 1000, LogLevel.Info, 'first');
632
+ log(state, 1099, LogLevel.Info, 'suppressed');
685
633
 
686
- log(LogLevel.Info, 'next-window');
634
+ log(state, 1100, LogLevel.Info, 'next-window');
687
635
 
688
- expect(forwarded.map((entry) => entry.data)).toEqual(['first', 'next-window']);
689
- } finally {
690
- vi.useRealTimers();
691
- }
636
+ expect(forwarded.map((entry) => entry.data)).toEqual(['first', 'next-window']);
692
637
  });
693
638
  });
694
639
 
@@ -696,232 +641,72 @@ describe('createSampledLogSink', () => {
696
641
  it('forwards 1-in-N entries', () => {
697
642
  const forwarded: LogEntry[] = [];
698
643
  const sampled = createSampledLogSink((e) => forwarded.push({ ...e }), 3);
699
- addLogSink(sampled);
700
- for (let i = 0; i < 9; i++) log(LogLevel.Info, `msg${i}`);
644
+ addLogSink(state, sampled);
645
+ for (let i = 0; i < 9; i++) log(state, 0, LogLevel.Info, `msg${i}`);
701
646
  expect(forwarded).toHaveLength(3);
702
647
  });
703
648
 
704
649
  it('passes all entries through when rate is 1', () => {
705
650
  const forwarded: LogEntry[] = [];
706
651
  const sampled = createSampledLogSink((e) => forwarded.push({ ...e }), 1);
707
- addLogSink(sampled);
708
- log(LogLevel.Info, 'a');
709
- log(LogLevel.Info, 'b');
652
+ addLogSink(state, sampled);
653
+ log(state, 0, LogLevel.Info, 'a');
654
+ log(state, 0, LogLevel.Info, 'b');
710
655
  expect(forwarded).toHaveLength(2);
711
656
  });
712
657
  });
713
658
 
714
659
  describe('createTextLogFormatter', () => {
715
660
  it('produces a readable prefix + message line', () => {
716
- const fmt = createTextLogFormatter();
717
- const entry: LogEntry = { level: LogLevel.Warn, channel: 'batch', data: 'test' };
718
- expect(fmt(entry)).toBe('[batch] test');
661
+ const fmt = createTextLogFormatter(state);
662
+ expect(fmt(entryOf(LogLevel.Warn, 'batch', 'test'))).toBe('[batch] test');
719
663
  });
720
664
 
721
- it('includes timestamp prefix when requested', () => {
722
- const fmt = createTextLogFormatter({ timestamp: true });
723
- const entry: LogEntry = { level: LogLevel.Info, channel: null, data: 'x' };
724
- expect(fmt(entry)).toMatch(/^t=\d+\.\d+ \[flight\] x$/);
665
+ it("includes the entry's timestamp when requested", () => {
666
+ const fmt = createTextLogFormatter(state, { timestamp: true });
667
+ expect(fmt(entryOf(LogLevel.Info, null, 'x', 12.345))).toBe('t=12.35 [flight] x');
725
668
  });
726
669
 
727
670
  it('includes level prefix when requested', () => {
728
- const fmt = createTextLogFormatter({ levelPrefix: true });
729
- const entry: LogEntry = { level: LogLevel.Error, channel: 'ch', data: 'boom' };
730
- expect(fmt(entry)).toBe('error [ch] boom');
671
+ const fmt = createTextLogFormatter(state, { levelPrefix: true });
672
+ expect(fmt(entryOf(LogLevel.Error, 'ch', 'boom'))).toBe('error [ch] boom');
731
673
  });
732
674
 
733
675
  it('labels an unknown numeric level', () => {
734
- const fmt = createTextLogFormatter({ levelPrefix: true });
735
- const entry: LogEntry = { level: 99 as LogLevel, channel: null, data: 'message' };
676
+ const fmt = createTextLogFormatter(state, { levelPrefix: true });
736
677
 
737
- expect(fmt(entry)).toBe('unknown [flight] message');
678
+ expect(fmt(entryOf(99 as LogLevel, null, 'message'))).toBe('unknown [flight] message');
738
679
  });
739
680
 
740
681
  it('serializes record data', () => {
741
- const fmt = createTextLogFormatter();
682
+ const fmt = createTextLogFormatter(state);
742
683
 
743
- expect(fmt({ level: LogLevel.Info, channel: null, data: { value: 3 } })).toBe('[flight] {"value":3}');
684
+ expect(fmt(entryOf(LogLevel.Info, null, { value: 3 }))).toBe('[flight] {"value":3}');
744
685
  });
745
686
 
746
- it('indents entries while a group is open', () => {
747
- beginLogGroup('outer');
748
- const fmt = createTextLogFormatter({ indentGroups: true });
687
+ it("indents entries while a group is open on the formatter's state", () => {
688
+ beginLogGroup(state, 0, 'outer');
689
+ const fmt = createTextLogFormatter(state, { indentGroups: true });
749
690
 
750
- const formatted = fmt({ level: LogLevel.Info, channel: null, data: 'inside' });
691
+ const formatted = fmt(entryOf(LogLevel.Info, null, 'inside'));
751
692
 
752
693
  expect(formatted).toBe('[flight] inside');
753
- clearLogGroups();
754
694
  });
755
695
  });
756
696
 
757
- describe('destroyFileLogSink', () => {
758
- it('awaits flush before destroying the transport', async () => {
759
- const events: string[] = [];
760
- let finishFlush: ((outcome: LogTransportFlushOutcome) => void) | undefined;
761
- const flushPromise = new Promise<LogTransportFlushOutcome>((resolve) => {
762
- finishFlush = resolve;
763
- });
764
- const transport = createTestLogTransport({
765
- destroy: async () => {
766
- events.push('destroy');
767
- return { reason: 'destroyed' };
768
- },
769
- flush: () => {
770
- events.push('flush-start');
771
- return flushPromise.then((outcome) => {
772
- events.push('flush-end');
773
- return outcome;
774
- });
775
- },
776
- });
777
-
778
- const closing = destroyFileLogSink(createFileLogSink(transport));
779
- expect(events).toEqual(['flush-start']);
780
- finishFlush?.({ delivery: 'operating-system', reason: 'drained' });
781
-
782
- await expect(closing).resolves.toEqual({
783
- destroy: { reason: 'destroyed' },
784
- flush: { delivery: 'operating-system', reason: 'drained' },
785
- reason: 'destroyed',
786
- });
787
- expect(events).toEqual(['flush-start', 'flush-end', 'destroy']);
788
- });
789
-
790
- it('attempts destroy and preserves both outcomes when flush fails', async () => {
791
- const events: string[] = [];
792
- const handle = createFileLogSink(
793
- createTestLogTransport({
794
- destroy: async () => {
795
- events.push('destroy');
796
- return { reason: 'destroyed' };
797
- },
798
- flush: async () => {
799
- events.push('flush');
800
- return { message: 'disk full', reason: 'operation-failed' };
801
- },
802
- }),
803
- );
804
-
805
- await expect(destroyFileLogSink(handle)).resolves.toEqual({
806
- destroy: { reason: 'destroyed' },
807
- flush: { message: 'disk full', reason: 'operation-failed' },
808
- reason: 'operation-failed',
809
- });
810
- expect(events).toEqual(['flush', 'destroy']);
811
- });
812
-
813
- it('keeps a successor destination live when an older handle is destroyed', async () => {
814
- const firstEvents: string[] = [];
815
- const secondLines: string[] = [];
816
- const first = createFileLogSink(
817
- createTestLogTransport({
818
- destroy: async () => {
819
- firstEvents.push('destroy');
820
- return { reason: 'destroyed' };
821
- },
822
- }),
823
- );
824
- const second = createFileLogSink(
825
- createTestLogTransport({
826
- write(line) {
827
- secondLines.push(line);
828
- return { reason: 'accepted' };
829
- },
830
- }),
831
- { formatter: () => 'second' },
832
- );
833
-
834
- await destroyFileLogSink(first);
835
- second.sink({ channel: null, data: 'still-live', level: LogLevel.Info });
836
-
837
- expect(firstEvents).toEqual(['destroy']);
838
- expect(secondLines).toEqual(['second\n']);
839
- });
840
-
841
- it('terminals and unregisters the sink before awaiting flush', async () => {
842
- const lines: string[] = [];
843
- let finishFlush: ((outcome: LogTransportFlushOutcome) => void) | undefined;
844
- const handle = createFileLogSink(
845
- createTestLogTransport({
846
- flush: () =>
847
- new Promise<LogTransportFlushOutcome>((resolve) => {
848
- finishFlush = resolve;
849
- }),
850
- write(line) {
851
- lines.push(line);
852
- return { reason: 'accepted' };
853
- },
854
- }),
855
- );
856
- addLogSink(handle.sink);
857
-
858
- const closing = destroyFileLogSink(handle);
859
- log(LogLevel.Info, 'after-destroy-started');
860
-
861
- expect(lines).toEqual([]);
862
- expect(removeLogSink(handle.sink)).toBe(false);
863
- finishFlush?.({ delivery: 'process-buffer', reason: 'drained' });
864
- await closing;
865
- });
866
-
867
- it('makes repeated teardown idempotent without repeating provider calls', async () => {
868
- let destroyCalls = 0;
869
- let flushCalls = 0;
870
- const handle = createFileLogSink(
871
- createTestLogTransport({
872
- destroy: async () => {
873
- destroyCalls++;
874
- return { reason: 'destroyed' };
875
- },
876
- flush: async () => {
877
- flushCalls++;
878
- return { delivery: 'durable-storage', reason: 'drained' };
879
- },
880
- }),
881
- );
882
-
883
- const first: FileLogSinkDestroyOutcome = await destroyFileLogSink(handle);
884
- const second = await destroyFileLogSink(handle);
885
-
886
- expect(first).toEqual({
887
- destroy: { reason: 'destroyed' },
888
- flush: { delivery: 'durable-storage', reason: 'drained' },
889
- reason: 'destroyed',
890
- });
891
- expect(second).toEqual({ ...first, reason: 'already-destroyed' });
892
- expect({ destroyCalls, flushCalls }).toEqual({ destroyCalls: 1, flushCalls: 1 });
893
- });
894
-
895
- it.each<LogTransportFlushOutcome>([
896
- { delivery: 'process-buffer', reason: 'drained' },
897
- { delivery: 'operating-system', reason: 'drained' },
898
- { delivery: 'durable-storage', reason: 'drained' },
899
- { delivery: 'remote-acknowledged', reason: 'drained' },
900
- ])('preserves the $delivery delivery boundary', async (flushOutcome) => {
901
- const handle = createFileLogSink(createTestLogTransport({ flush: async () => flushOutcome }));
902
-
903
- const outcome = await destroyFileLogSink(handle);
904
-
905
- expect(outcome.flush).toEqual(flushOutcome);
906
- });
697
+ describe('disposeLogSink', () => {
698
+ it('flushes queued entries and leaves the sink callable', () => {
699
+ const forwarded: LogEntry[] = [];
700
+ const handle = createBufferedLogSink((e) => forwarded.push({ ...e }), { size: 100 });
701
+ handle.sink(entryOf(LogLevel.Info, null, 'pending'));
907
702
 
908
- it('converts rejected flush and destroy operations into a composite failure', async () => {
909
- const handle = createFileLogSink(
910
- createTestLogTransport({
911
- destroy: () => Promise.reject(new Error('close failed')),
912
- flush: () => Promise.reject(new Error('flush failed')),
913
- }),
914
- );
703
+ disposeLogSink(handle);
704
+ handle.sink(entryOf(LogLevel.Info, null, 'after'));
705
+ flushLogSink(handle);
915
706
 
916
- await expect(destroyFileLogSink(handle)).resolves.toEqual({
917
- destroy: { message: 'close failed', reason: 'operation-failed' },
918
- flush: { message: 'flush failed', reason: 'operation-failed' },
919
- reason: 'operation-failed',
920
- });
707
+ expect(forwarded.map((entry) => entry.data)).toEqual(['pending', 'after']);
921
708
  });
922
- });
923
709
 
924
- describe('disposeLogSink', () => {
925
710
  it('does nothing for an unknown handle', () => {
926
711
  const unknown: BufferedLogSink = { [EntityRuntimeKey]: undefined, sink: () => {} };
927
712
 
@@ -930,40 +715,53 @@ describe('disposeLogSink', () => {
930
715
  });
931
716
 
932
717
  describe('enableLogSignals', () => {
933
- afterEach(() => {
934
- // Reset signals (they are lazy-created; clearLogSinks does not reset them)
935
- // We test with fresh sinks to avoid cross-test coupling.
936
- clearLogSinks();
937
- });
938
-
939
718
  it('returns a LogSignals entity with onLogEntry and onLogError signals', () => {
940
- const signals: LogSignals = enableLogSignals();
719
+ const signals: LogSignals = enableLogSignals(state);
941
720
  expect(signals.onLogEntry).toBeDefined();
942
721
  expect(signals.onLogError).toBeDefined();
722
+ expect(state.signals).toBe(signals);
943
723
  });
944
724
 
945
725
  it('returns the same object on subsequent calls', () => {
946
- const a = enableLogSignals();
947
- const b = enableLogSignals();
726
+ const a = enableLogSignals(state);
727
+ const b = enableLogSignals(state);
948
728
  expect(a).toBe(b);
949
729
  });
950
730
 
731
+ it('gives each state its own signals', () => {
732
+ expect(enableLogSignals(state)).not.toBe(enableLogSignals(createLogState()));
733
+ });
734
+
735
+ it('types both signals by their entry payload and stops a slot disconnected by its SlotId', () => {
736
+ const signals = enableLogSignals(state);
737
+ expectTypeOf(signals.onLogEntry).toEqualTypeOf<Signal<Readonly<LogEntry>>>();
738
+ expectTypeOf(signals.onLogError).toEqualTypeOf<Signal<Readonly<LogEntry>>>();
739
+ const received: string[] = [];
740
+ const id: SlotId = connectSignal(signals.onLogEntry, (entry: Readonly<LogEntry>) => {
741
+ received.push(String(entry.data));
742
+ });
743
+ log(state, 0, LogLevel.Info, 'first');
744
+ disconnectSignal(signals.onLogEntry, id);
745
+ log(state, 0, LogLevel.Info, 'second');
746
+ expect(received).toEqual(['first']);
747
+ });
748
+
951
749
  it('onLogEntry fires for every emitted entry', () => {
952
- const signals = enableLogSignals();
750
+ const signals = enableLogSignals(state);
953
751
  const received: LogEntry[] = [];
954
752
  connectSignal(signals.onLogEntry, (e) => received.push({ ...e }));
955
753
  // Even with no sinks the signal path fires (signals bypass the sinks-empty fast path)
956
- log(LogLevel.Info, 'via-signal');
754
+ log(state, 0, LogLevel.Info, 'via-signal');
957
755
  expect(received).toHaveLength(1);
958
756
  expect(received[0].data).toBe('via-signal');
959
757
  });
960
758
 
961
759
  it('onLogError fires only for Error-level entries', () => {
962
- const signals = enableLogSignals();
760
+ const signals = enableLogSignals(state);
963
761
  const errors: LogEntry[] = [];
964
762
  connectSignal(signals.onLogError, (e) => errors.push({ ...e }));
965
- log(LogLevel.Info, 'not-error');
966
- log(LogLevel.Error, 'is-error');
763
+ log(state, 0, LogLevel.Info, 'not-error');
764
+ log(state, 0, LogLevel.Error, 'is-error');
967
765
  expect(errors).toHaveLength(1);
968
766
  expect(errors[0].level).toBe(LogLevel.Error);
969
767
  });
@@ -972,131 +770,161 @@ describe('enableLogSignals', () => {
972
770
  describe('endLogGroup', () => {
973
771
  it('emits a Debug group-end entry and decrements nesting depth', () => {
974
772
  const { entries } = recordingSink();
975
- beginLogGroup('setup');
773
+ beginLogGroup(state, 0, 'setup');
976
774
  entries.length = 0; // clear begin entry
977
- endLogGroup();
775
+ endLogGroup(state, 9);
978
776
  expect(entries).toHaveLength(1);
979
- expect(entries[0].data).toMatchObject({ group: 'end' });
777
+ expect(entries[0].data).toMatchObject({ group: 'end', depth: 1 });
778
+ expect(entries[0].timestampMs).toBe(9);
779
+ expect(state.groupDepth).toBe(0);
980
780
  });
981
781
 
982
782
  it('is a no-op when no group is open', () => {
983
783
  const { entries } = recordingSink();
984
- endLogGroup();
784
+ endLogGroup(state, 0);
985
785
  expect(entries).toHaveLength(0);
986
786
  });
987
787
 
988
788
  it('closes the group without emitting when Debug is suppressed', () => {
989
789
  const { entries } = recordingSink();
990
- beginLogGroup('visible');
790
+ beginLogGroup(state, 0, 'visible');
991
791
  entries.length = 0;
992
- setLogLevel(LogLevel.Error);
792
+ setLogLevel(state, LogLevel.Error);
993
793
 
994
- endLogGroup();
794
+ endLogGroup(state, 0);
995
795
 
996
796
  expect(entries).toHaveLength(0);
797
+ expect(state.groupDepth).toBe(0);
997
798
  });
998
799
  });
999
800
 
1000
801
  describe('endLogTimer', () => {
1001
802
  it('emits a Debug entry with label and elapsedMs fields and returns elapsed', () => {
1002
803
  const entries: LogEntry[] = [];
1003
- addLogSink((e) => entries.push({ ...e }));
1004
- const timer = startLogTimer('op', 'perf');
1005
- const elapsed = endLogTimer(timer);
1006
- expect(elapsed).toBeGreaterThanOrEqual(0);
804
+ addLogSink(state, (e) => entries.push({ ...e }));
805
+ const timer = startLogTimer('op', 'perf', 10);
806
+ const elapsed = endLogTimer(state, 25, timer);
807
+ expect(elapsed).toBe(15);
1007
808
  expect(entries).toHaveLength(1);
1008
809
  expect(entries[0].level).toBe(LogLevel.Debug);
1009
810
  expect(entries[0].channel).toBe('perf');
1010
- expect(entries[0].data).toMatchObject({ label: 'op' });
811
+ expect(entries[0].timestampMs).toBe(25);
812
+ expect(entries[0].data).toMatchObject({ label: 'op', elapsedMs: 15 });
1011
813
  });
1012
814
  });
1013
815
 
1014
816
  describe('enterLogSpan', () => {
1015
- afterEach(() => {
1016
- // Ensure spans are cleaned up
1017
- const span = createLogSpan('cleanup');
1018
- exitLogSpan(span);
1019
- });
1020
-
1021
817
  it('merges span fields into emitted entries while the span is active', () => {
1022
818
  const { entries } = recordingSink();
1023
- const span = createLogSpan('request', { reqId: 'abc' });
1024
- enterLogSpan(span);
1025
- log(LogLevel.Info, 'inside span');
1026
- exitLogSpan(span);
819
+ const span = spanOf('request', { reqId: 'abc' });
820
+ enterLogSpan(state, span);
821
+ log(state, 0, LogLevel.Info, 'inside span');
822
+ exitLogSpan(state, span);
1027
823
  expect(entries[0].data).toMatchObject({ reqId: 'abc' });
1028
824
  });
1029
825
 
1030
826
  it('does not merge span fields after exitLogSpan', () => {
1031
827
  const { entries } = recordingSink();
1032
- const span = createLogSpan('request', { reqId: 'def' });
1033
- enterLogSpan(span);
1034
- exitLogSpan(span);
1035
- log(LogLevel.Info, 'outside span');
828
+ const span = spanOf('request', { reqId: 'def' });
829
+ enterLogSpan(state, span);
830
+ exitLogSpan(state, span);
831
+ log(state, 0, LogLevel.Info, 'outside span');
1036
832
  expect(entries[0].data).toBe('outside span');
1037
833
  });
1038
834
 
1039
835
  it('newer spans win on field key collision', () => {
1040
836
  const { entries } = recordingSink();
1041
- const span1 = createLogSpan('outer', { x: 1, y: 10 });
1042
- const span2 = createLogSpan('inner', { x: 2 });
1043
- enterLogSpan(span1);
1044
- enterLogSpan(span2);
1045
- log(LogLevel.Info, 'nested');
1046
- exitLogSpan(span2);
1047
- exitLogSpan(span1);
837
+ const span1 = spanOf('outer', { x: 1, y: 10 });
838
+ const span2 = spanOf('inner', { x: 2 });
839
+ enterLogSpan(state, span1);
840
+ enterLogSpan(state, span2);
841
+ log(state, 0, LogLevel.Info, 'nested');
842
+ exitLogSpan(state, span2);
843
+ exitLogSpan(state, span1);
1048
844
  expect((entries[0].data as Record<string, unknown>).x).toBe(2);
1049
845
  expect((entries[0].data as Record<string, unknown>).y).toBe(10);
1050
846
  });
1051
847
 
1052
848
  it('leaves data unchanged when active spans have no fields', () => {
1053
849
  const { entries } = recordingSink();
1054
- const span = createLogSpan('empty');
1055
- enterLogSpan(span);
850
+ const span = spanOf('empty');
851
+ enterLogSpan(state, span);
1056
852
 
1057
- log(LogLevel.Info, 'unchanged');
1058
- exitLogSpan(span);
853
+ log(state, 0, LogLevel.Info, 'unchanged');
854
+ exitLogSpan(state, span);
1059
855
 
1060
856
  expect(entries[0].data).toBe('unchanged');
1061
857
  });
1062
858
 
1063
859
  it('merges active span fields into record data with direct fields winning', () => {
1064
860
  const { entries } = recordingSink();
1065
- const span = createLogSpan('record', { inherited: 1, winner: 'span' });
1066
- enterLogSpan(span);
861
+ const span = spanOf('record', { inherited: 1, winner: 'span' });
862
+ enterLogSpan(state, span);
1067
863
 
1068
- log(LogLevel.Info, { direct: 2, winner: 'data' });
1069
- exitLogSpan(span);
864
+ log(state, 0, LogLevel.Info, { direct: 2, winner: 'data' });
865
+ exitLogSpan(state, span);
1070
866
 
1071
867
  expect(entries[0].data).toEqual({ direct: 2, inherited: 1, winner: 'data' });
1072
868
  });
869
+
870
+ it('does not leak an active span into another state', () => {
871
+ const other = createLogState();
872
+ const { entries } = recordingSink(other);
873
+ enterLogSpan(state, spanOf('mine', { leaked: true }));
874
+
875
+ log(other, 0, LogLevel.Info, 'clean');
876
+
877
+ expect(entries[0].data).toBe('clean');
878
+ });
1073
879
  });
1074
880
 
1075
881
  describe('exitLogSpan', () => {
1076
882
  it('is a no-op when the span is not in the stack', () => {
1077
883
  const { entries } = recordingSink();
1078
- const span = createLogSpan('phantom', { z: 1 });
1079
- exitLogSpan(span);
1080
- log(LogLevel.Info, 'clean');
884
+ const span = spanOf('phantom', { z: 1 });
885
+ exitLogSpan(state, span);
886
+ log(state, 0, LogLevel.Info, 'clean');
1081
887
  expect(entries[0].data).toBe('clean');
1082
888
  });
1083
889
 
1084
- it('supports out-of-order exit (removes by identity)', () => {
890
+ it('supports out-of-order exit', () => {
1085
891
  const { entries } = recordingSink();
1086
- const span1 = createLogSpan('a', { a: 1 });
1087
- const span2 = createLogSpan('b', { b: 2 });
1088
- enterLogSpan(span1);
1089
- enterLogSpan(span2);
892
+ const span1 = spanOf('a', { a: 1 });
893
+ const span2 = spanOf('b', { b: 2 });
894
+ enterLogSpan(state, span1);
895
+ enterLogSpan(state, span2);
1090
896
  // Exit span1 first even though span2 was entered last
1091
- exitLogSpan(span1);
1092
- log(LogLevel.Info, 'after-a-exit');
1093
- exitLogSpan(span2);
897
+ exitLogSpan(state, span1);
898
+ log(state, 0, LogLevel.Info, 'after-a-exit');
899
+ exitLogSpan(state, span2);
1094
900
  expect((entries[0].data as Record<string, unknown>).b).toBe(2);
1095
901
  expect((entries[0].data as Record<string, unknown>).a).toBeUndefined();
1096
902
  });
903
+
904
+ it('matches the active span by id rather than object identity', () => {
905
+ const { entries } = recordingSink();
906
+ const span = spanOf('a', { a: 1 });
907
+ enterLogSpan(state, span);
908
+
909
+ exitLogSpan(state, { ...span });
910
+ log(state, 0, LogLevel.Info, 'exited');
911
+
912
+ expect(entries[0].data).toBe('exited');
913
+ });
1097
914
  });
1098
915
 
1099
916
  describe('flushLogSink', () => {
917
+ it('forwards queued entries to the target in order', () => {
918
+ const forwarded: LogEntry[] = [];
919
+ const handle = createBufferedLogSink((e) => forwarded.push({ ...e }), { size: 100 });
920
+ handle.sink(entryOf(LogLevel.Info, null, 'a'));
921
+ handle.sink(entryOf(LogLevel.Info, null, 'b'));
922
+
923
+ flushLogSink(handle);
924
+
925
+ expect(forwarded.map((entry) => entry.data)).toEqual(['a', 'b']);
926
+ });
927
+
1100
928
  it('does nothing for an unknown handle', () => {
1101
929
  const unknown: BufferedLogSink = { [EntityRuntimeKey]: undefined, sink: () => {} };
1102
930
 
@@ -1106,26 +934,26 @@ describe('flushLogSink', () => {
1106
934
 
1107
935
  describe('getLogChannelLevel', () => {
1108
936
  it('returns null when no channel level is set', () => {
1109
- expect(getLogChannelLevel('unknown')).toBeNull();
937
+ expect(getLogChannelLevel(state, 'unknown')).toBeNull();
1110
938
  });
1111
939
 
1112
940
  it('returns the set level for a known channel', () => {
1113
- setLogChannelLevel('render', LogLevel.Error);
1114
- expect(getLogChannelLevel('render')).toBe(LogLevel.Error);
941
+ setLogChannelLevel(state, 'render', LogLevel.Error);
942
+ expect(getLogChannelLevel(state, 'render')).toBe(LogLevel.Error);
1115
943
  });
1116
944
  });
1117
945
 
1118
946
  describe('getLogConsoleLevel', () => {
1119
947
  it('returns the current threshold', () => {
1120
- setLogConsoleLevel(LogLevel.Verbose);
1121
- expect(getLogConsoleLevel()).toBe(LogLevel.Verbose);
948
+ setLogConsoleLevel(state, LogLevel.Verbose);
949
+ expect(getLogConsoleLevel(state)).toBe(LogLevel.Verbose);
1122
950
  });
1123
951
  });
1124
952
 
1125
953
  describe('getLogLevel', () => {
1126
954
  it('returns the current global emit level', () => {
1127
- setLogLevel(LogLevel.Error);
1128
- expect(getLogLevel()).toBe(LogLevel.Error);
955
+ setLogLevel(state, LogLevel.Error);
956
+ expect(getLogLevel(state)).toBe(LogLevel.Error);
1129
957
  });
1130
958
  });
1131
959
 
@@ -1145,75 +973,190 @@ describe('getLogLevelName', () => {
1145
973
  });
1146
974
 
1147
975
  describe('getMemoryLogSinkEntries', () => {
1148
- it('returns empty array before any entries', () => {
976
+ it('writes an empty list before any entries', () => {
977
+ const handle = createMemoryLogSink(5);
978
+ expect(memoryEntries(handle)).toHaveLength(0);
979
+ });
980
+
981
+ it('clears out before writing', () => {
1149
982
  const handle = createMemoryLogSink(5);
1150
- expect(getMemoryLogSinkEntries(handle)).toHaveLength(0);
983
+ handle.sink(entryOf(LogLevel.Info, null, 'only'));
984
+ const out = [entryOf(LogLevel.Error, null, 'stale')];
985
+
986
+ getMemoryLogSinkEntries(out, handle);
987
+
988
+ expect(out.map((entry) => entry.data)).toEqual(['only']);
1151
989
  });
1152
990
 
1153
- it('returns an empty array for an unknown handle', () => {
991
+ it('writes an empty list for an unknown handle', () => {
1154
992
  const unknown: MemoryLogSink = { [EntityRuntimeKey]: undefined, sink: () => {} };
993
+ const out = [entryOf(LogLevel.Error, null, 'stale')];
994
+
995
+ getMemoryLogSinkEntries(out, unknown);
996
+
997
+ expect(out).toEqual([]);
998
+ });
999
+ });
1000
+
1001
+ describe('initializeBufferedLogSink', () => {
1002
+ it('writes a buffered sink over the target into out', () => {
1003
+ const forwarded: LogEntry[] = [];
1004
+ const out = allocateEntity<BufferedLogSink>();
1005
+
1006
+ initializeBufferedLogSink(out, (e) => forwarded.push({ ...e }), { size: 1 });
1007
+ out.sink(entryOf(LogLevel.Info, null, 'flushed-at-size'));
1008
+
1009
+ expect(forwarded).toHaveLength(1);
1010
+ });
1011
+ });
1012
+
1013
+ describe('initializeLogContext', () => {
1014
+ it('resets a context to no channel and no fields', () => {
1015
+ const context = contextOf('render', { a: 1 });
1016
+
1017
+ initializeLogContext(context);
1018
+
1019
+ expect(context.channel).toBeNull();
1020
+ expect(context.fields).toEqual({});
1021
+ });
1022
+ });
1023
+
1024
+ describe('initializeLogSpan', () => {
1025
+ it('assigns the next id from the state and clears name, channel, and fields', () => {
1026
+ const span = spanOf('named', { a: 1 }, 'ch');
1027
+
1028
+ initializeLogSpan(span, state);
1029
+
1030
+ expect(span.id).toBe(2);
1031
+ expect(span.name).toBe('');
1032
+ expect(span.channel).toBeNull();
1033
+ expect(span.fields).toEqual({});
1034
+ expect(state.nextSpanId).toBe(3);
1035
+ });
1036
+ });
1037
+
1038
+ describe('initializeLogState', () => {
1039
+ it('resets every field of an existing state', () => {
1040
+ addLogSink(state, () => {});
1041
+ setLogLevel(state, LogLevel.Error);
1042
+ setLogConsoleLevel(state, LogLevel.None);
1043
+ setLogChannelLevel(state, 'ch', LogLevel.Warn);
1044
+ logOnce(state, 0, 'key', LogLevel.Warn, 'x');
1045
+ setLogRedactionPaths(state, ['a']);
1046
+ registerLogSerializer(state, 'k', () => ({}));
1047
+ beginLogGroup(state, 0, 'g');
1048
+ enterLogSpan(state, spanOf('s'));
1049
+ enableLogSignals(state);
1050
+
1051
+ initializeLogState(state);
1052
+
1053
+ expect(state.sinks).toEqual([]);
1054
+ expect(state.level).toBe(LogLevel.Verbose);
1055
+ expect(state.consoleLevel).toBe(LogLevel.Info);
1056
+ expect(state.channelLevels.size).toBe(0);
1057
+ expect(state.onceKeys.size).toBe(0);
1058
+ expect(state.redactionPaths).toEqual([]);
1059
+ expect(state.serializers.size).toBe(0);
1060
+ expect(state.groupDepth).toBe(0);
1061
+ expect(state.spans).toEqual([]);
1062
+ expect(state.signals).toBeNull();
1063
+ expect(state.nextSpanId).toBe(1);
1064
+ });
1065
+ });
1066
+
1067
+ describe('initializeMemoryLogSink', () => {
1068
+ it('writes an empty ring buffer of the given capacity into out', () => {
1069
+ const out = allocateEntity<MemoryLogSink>();
1070
+
1071
+ initializeMemoryLogSink(out, 1);
1072
+ out.sink(entryOf(LogLevel.Info, null, 'a'));
1073
+ out.sink(entryOf(LogLevel.Info, null, 'b'));
1155
1074
 
1156
- expect(getMemoryLogSinkEntries(unknown)).toEqual([]);
1075
+ expect(memoryEntries(out as MemoryLogSink).map((entry) => entry.data)).toEqual(['b']);
1076
+ });
1077
+ });
1078
+
1079
+ describe('initializeRateLimitedLogSink', () => {
1080
+ it('writes a rate-limited sink over the target into out', () => {
1081
+ const forwarded: LogEntry[] = [];
1082
+ const out = allocateEntity<RateLimitedLogSink>();
1083
+
1084
+ initializeRateLimitedLogSink(out, (e) => forwarded.push({ ...e }), { intervalMs: 10, maxPerInterval: 1 });
1085
+ out.sink(entryOf(LogLevel.Info, null, 'a', 0));
1086
+ out.sink(entryOf(LogLevel.Info, null, 'b', 5));
1087
+
1088
+ expect(forwarded.map((entry) => entry.data)).toEqual(['a']);
1157
1089
  });
1158
1090
  });
1159
1091
 
1160
1092
  describe('log', () => {
1161
- it('forwards level, channel, and data to all sinks', () => {
1093
+ it('forwards level, channel, data, and the caller timestamp to all sinks', () => {
1162
1094
  const { entries } = recordingSink();
1163
- log(LogLevel.Warn, { k: 1 }, 'shader');
1164
- expect(entries[0]).toEqual({ level: LogLevel.Warn, channel: 'shader', data: { k: 1 } });
1095
+ log(state, 3.5, LogLevel.Warn, { k: 1 }, 'shader');
1096
+ expect(entries[0]).toEqual({ level: LogLevel.Warn, channel: 'shader', data: { k: 1 }, timestampMs: 3.5 });
1165
1097
  });
1166
1098
 
1167
1099
  it('defaults the channel to null', () => {
1168
1100
  const { entries } = recordingSink();
1169
- log(LogLevel.Info, 'x');
1101
+ log(state, 0, LogLevel.Info, 'x');
1170
1102
  expect(entries[0].channel).toBeNull();
1171
1103
  });
1172
1104
 
1173
1105
  it('does nothing when no sink is installed', () => {
1174
1106
  const debug = vi.spyOn(console, 'debug').mockImplementation(() => {});
1175
- expect(() => log(LogLevel.Info, 'x')).not.toThrow();
1107
+ expect(() => log(state, 0, LogLevel.Info, 'x')).not.toThrow();
1176
1108
  expect(debug).not.toHaveBeenCalled();
1177
1109
  });
1178
1110
 
1179
1111
  it('accepts a lazy data provider thunk', () => {
1180
1112
  const { entries } = recordingSink();
1181
1113
  const provider = vi.fn(() => 'lazy-value');
1182
- log(LogLevel.Info, provider);
1114
+ log(state, 0, LogLevel.Info, provider);
1183
1115
  expect(provider).toHaveBeenCalledTimes(1);
1184
1116
  expect(entries[0].data).toBe('lazy-value');
1185
1117
  });
1186
1118
 
1187
1119
  it('does not call the thunk when the level is suppressed', () => {
1188
1120
  recordingSink();
1189
- setLogLevel(LogLevel.Error);
1121
+ setLogLevel(state, LogLevel.Error);
1190
1122
  const provider = vi.fn(() => 'should-not-be-called');
1191
- log(LogLevel.Verbose, provider);
1123
+ log(state, 0, LogLevel.Verbose, provider);
1192
1124
  expect(provider).not.toHaveBeenCalled();
1193
1125
  });
1194
1126
 
1195
1127
  it('fans out to multiple sinks', () => {
1196
1128
  const a: LogEntry[] = [];
1197
1129
  const b: LogEntry[] = [];
1198
- addLogSink((e) => a.push({ ...e }));
1199
- addLogSink((e) => b.push({ ...e }));
1200
- log(LogLevel.Info, 'multi');
1130
+ addLogSink(state, (e) => a.push({ ...e }));
1131
+ addLogSink(state, (e) => b.push({ ...e }));
1132
+ log(state, 0, LogLevel.Info, 'multi');
1201
1133
  expect(a).toHaveLength(1);
1202
1134
  expect(b).toHaveLength(1);
1203
1135
  });
1136
+
1137
+ it('never reads a clock', () => {
1138
+ recordingSink();
1139
+ const now = vi.spyOn(Date, 'now');
1140
+ const performanceNow = vi.spyOn(performance, 'now');
1141
+
1142
+ log(state, 1, LogLevel.Info, 'x');
1143
+
1144
+ expect(now).not.toHaveBeenCalled();
1145
+ expect(performanceNow).not.toHaveBeenCalled();
1146
+ });
1204
1147
  });
1205
1148
 
1206
1149
  describe('logAssert', () => {
1207
1150
  it('emits an Error entry when condition is false', () => {
1208
1151
  const { entries } = recordingSink();
1209
- logAssert(false, 'assertion failed');
1152
+ logAssert(state, 0, false, 'assertion failed');
1210
1153
  expect(entries).toHaveLength(1);
1211
1154
  expect(entries[0].level).toBe(LogLevel.Error);
1212
1155
  });
1213
1156
 
1214
1157
  it('does not emit when condition is true', () => {
1215
1158
  const { entries } = recordingSink();
1216
- logAssert(true, 'should not emit');
1159
+ logAssert(state, 0, true, 'should not emit');
1217
1160
  expect(entries).toHaveLength(0);
1218
1161
  });
1219
1162
  });
@@ -1221,13 +1164,13 @@ describe('logAssert', () => {
1221
1164
  describe('logDebug', () => {
1222
1165
  it('emits at LogLevel.Debug', () => {
1223
1166
  const { entries } = recordingSink();
1224
- logDebug('d', 'chan');
1225
- expect(entries[0]).toEqual({ level: LogLevel.Debug, channel: 'chan', data: 'd' });
1167
+ logDebug(state, 0, 'd', 'chan');
1168
+ expect(entries[0]).toEqual({ level: LogLevel.Debug, channel: 'chan', data: 'd', timestampMs: 0 });
1226
1169
  });
1227
1170
 
1228
1171
  it('accepts a lazy provider', () => {
1229
1172
  const { entries } = recordingSink();
1230
- logDebug(() => 'lazy', null);
1173
+ logDebug(state, 0, () => 'lazy', null);
1231
1174
  expect(entries[0].data).toBe('lazy');
1232
1175
  });
1233
1176
  });
@@ -1235,8 +1178,8 @@ describe('logDebug', () => {
1235
1178
  describe('logDebugWith', () => {
1236
1179
  it('emits at Debug with merged context fields', () => {
1237
1180
  const { entries } = recordingSink();
1238
- const ctx = createLogContext('ch', { reqId: 'abc' });
1239
- logDebugWith(ctx, 'msg');
1181
+ const ctx = contextOf('ch', { reqId: 'abc' });
1182
+ logDebugWith(state, 0, ctx, 'msg');
1240
1183
  expect(entries[0]).toMatchObject({ level: LogLevel.Debug, channel: 'ch', data: { msg: 'msg', reqId: 'abc' } });
1241
1184
  });
1242
1185
  });
@@ -1244,7 +1187,7 @@ describe('logDebugWith', () => {
1244
1187
  describe('logError', () => {
1245
1188
  it('emits at LogLevel.Error', () => {
1246
1189
  const { entries } = recordingSink();
1247
- logError('e');
1190
+ logError(state, 0, 'e');
1248
1191
  expect(entries[0].level).toBe(LogLevel.Error);
1249
1192
  });
1250
1193
  });
@@ -1252,8 +1195,8 @@ describe('logError', () => {
1252
1195
  describe('logErrorWith', () => {
1253
1196
  it('emits at Error with merged context fields', () => {
1254
1197
  const { entries } = recordingSink();
1255
- const ctx = createLogContext('ch', { reqId: '1' });
1256
- logErrorWith(ctx, 'fail');
1198
+ const ctx = contextOf('ch', { reqId: '1' });
1199
+ logErrorWith(state, 0, ctx, 'fail');
1257
1200
  expect(entries[0]).toMatchObject({ level: LogLevel.Error, data: { msg: 'fail', reqId: '1' } });
1258
1201
  });
1259
1202
  });
@@ -1261,7 +1204,7 @@ describe('logErrorWith', () => {
1261
1204
  describe('logInfo', () => {
1262
1205
  it('emits at LogLevel.Info', () => {
1263
1206
  const { entries } = recordingSink();
1264
- logInfo('i');
1207
+ logInfo(state, 0, 'i');
1265
1208
  expect(entries[0].level).toBe(LogLevel.Info);
1266
1209
  });
1267
1210
  });
@@ -1269,8 +1212,8 @@ describe('logInfo', () => {
1269
1212
  describe('logInfoWith', () => {
1270
1213
  it('emits at Info with merged context fields', () => {
1271
1214
  const { entries } = recordingSink();
1272
- const ctx = createLogContext('ch', { v: 2 });
1273
- logInfoWith(ctx, { extra: true });
1215
+ const ctx = contextOf('ch', { v: 2 });
1216
+ logInfoWith(state, 0, ctx, { extra: true });
1274
1217
  expect(entries[0].data).toMatchObject({ v: 2, extra: true });
1275
1218
  });
1276
1219
  });
@@ -1278,30 +1221,30 @@ describe('logInfoWith', () => {
1278
1221
  describe('logOnce', () => {
1279
1222
  it('emits only the first time for a given key', () => {
1280
1223
  const { entries } = recordingSink();
1281
- logOnce('key1', LogLevel.Warn, 'first');
1282
- logOnce('key1', LogLevel.Warn, 'second');
1224
+ logOnce(state, 0, 'key1', LogLevel.Warn, 'first');
1225
+ logOnce(state, 0, 'key1', LogLevel.Warn, 'second');
1283
1226
  expect(entries).toHaveLength(1);
1284
1227
  expect(entries[0].data).toBe('first');
1285
1228
  });
1286
1229
 
1287
1230
  it('allows different keys to emit independently', () => {
1288
1231
  const { entries } = recordingSink();
1289
- logOnce('key2a', LogLevel.Info, 'a');
1290
- logOnce('key2b', LogLevel.Info, 'b');
1232
+ logOnce(state, 0, 'key2a', LogLevel.Info, 'a');
1233
+ logOnce(state, 0, 'key2b', LogLevel.Info, 'b');
1291
1234
  expect(entries).toHaveLength(2);
1292
1235
  });
1293
1236
 
1294
1237
  it('returns true on first emit, false on subsequent calls', () => {
1295
1238
  recordingSink();
1296
- expect(logOnce('key3', LogLevel.Info, 'x')).toBe(true);
1297
- expect(logOnce('key3', LogLevel.Info, 'x')).toBe(false);
1239
+ expect(logOnce(state, 0, 'key3', LogLevel.Info, 'x')).toBe(true);
1240
+ expect(logOnce(state, 0, 'key3', LogLevel.Info, 'x')).toBe(false);
1298
1241
  });
1299
1242
  });
1300
1243
 
1301
1244
  describe('logVerbose', () => {
1302
1245
  it('emits at LogLevel.Verbose', () => {
1303
1246
  const { entries } = recordingSink();
1304
- logVerbose('v');
1247
+ logVerbose(state, 0, 'v');
1305
1248
  expect(entries[0].level).toBe(LogLevel.Verbose);
1306
1249
  });
1307
1250
  });
@@ -1309,8 +1252,8 @@ describe('logVerbose', () => {
1309
1252
  describe('logVerboseWith', () => {
1310
1253
  it('emits at Verbose with merged context fields', () => {
1311
1254
  const { entries } = recordingSink();
1312
- const ctx = createLogContext(null, { trace: true });
1313
- logVerboseWith(ctx, 'trace-msg');
1255
+ const ctx = contextOf(null, { trace: true });
1256
+ logVerboseWith(state, 0, ctx, 'trace-msg');
1314
1257
  expect(entries[0].data).toMatchObject({ msg: 'trace-msg', trace: true });
1315
1258
  });
1316
1259
  });
@@ -1318,7 +1261,7 @@ describe('logVerboseWith', () => {
1318
1261
  describe('logWarn', () => {
1319
1262
  it('emits at LogLevel.Warn', () => {
1320
1263
  const { entries } = recordingSink();
1321
- logWarn('w');
1264
+ logWarn(state, 0, 'w');
1322
1265
  expect(entries[0].level).toBe(LogLevel.Warn);
1323
1266
  });
1324
1267
  });
@@ -1326,8 +1269,8 @@ describe('logWarn', () => {
1326
1269
  describe('logWarnWith', () => {
1327
1270
  it('emits at Warn with merged context fields', () => {
1328
1271
  const { entries } = recordingSink();
1329
- const ctx = createLogContext('ch', { ctx: 'val' });
1330
- logWarnWith(ctx, 'warning');
1272
+ const ctx = contextOf('ch', { ctx: 'val' });
1273
+ logWarnWith(state, 0, ctx, 'warning');
1331
1274
  expect(entries[0].data).toMatchObject({ msg: 'warning', ctx: 'val' });
1332
1275
  });
1333
1276
  });
@@ -1335,24 +1278,31 @@ describe('logWarnWith', () => {
1335
1278
  describe('logWith', () => {
1336
1279
  it('emits at the given level with channel from context', () => {
1337
1280
  const { entries } = recordingSink();
1338
- const ctx = createLogContext('render', { frame: 1 });
1339
- logWith(ctx, LogLevel.Info, 'update');
1281
+ const ctx = contextOf('render', { frame: 1 });
1282
+ logWith(state, 0, ctx, LogLevel.Info, 'update');
1340
1283
  expect(entries[0]).toMatchObject({ level: LogLevel.Info, channel: 'render', data: { msg: 'update', frame: 1 } });
1341
1284
  });
1342
1285
 
1343
1286
  it('passes record data through with fields merged', () => {
1344
1287
  const { entries } = recordingSink();
1345
- const ctx = createLogContext(null, { base: 1 });
1346
- logWith(ctx, LogLevel.Debug, { extra: 2 });
1288
+ const ctx = contextOf(null, { base: 1 });
1289
+ logWith(state, 0, ctx, LogLevel.Debug, { extra: 2 });
1347
1290
  expect(entries[0].data).toEqual({ base: 1, extra: 2 });
1348
1291
  });
1349
1292
 
1350
1293
  it('accepts a lazy provider', () => {
1351
1294
  const { entries } = recordingSink();
1352
- const ctx = createLogContext(null, {});
1353
- logWith(ctx, LogLevel.Info, () => 'lazy');
1295
+ const ctx = contextOf(null);
1296
+ logWith(state, 0, ctx, LogLevel.Info, () => 'lazy');
1354
1297
  expect(entries[0].data).toBe('lazy');
1355
1298
  });
1299
+
1300
+ it('gates on the context channel level', () => {
1301
+ const { entries } = recordingSink();
1302
+ setLogChannelLevel(state, 'quiet', LogLevel.Error);
1303
+ logWith(state, 0, contextOf('quiet'), LogLevel.Info, 'suppressed');
1304
+ expect(entries).toHaveLength(0);
1305
+ });
1356
1306
  });
1357
1307
 
1358
1308
  describe('parseLogLevel', () => {
@@ -1378,19 +1328,18 @@ describe('parseLogLevel', () => {
1378
1328
 
1379
1329
  describe('registerLogSerializer', () => {
1380
1330
  it('applies the serializer when the JSON formatter encounters a matching __kind', () => {
1381
- registerLogSerializer('acme.Point', (v) => {
1331
+ registerLogSerializer(state, 'acme.Point', (v) => {
1382
1332
  const p = v as { x: number; y: number };
1383
1333
  return { serialized: `(${p.x},${p.y})` };
1384
1334
  });
1385
- const fmt = createJsonLogFormatter();
1386
- const entry: LogEntry = { level: LogLevel.Info, channel: null, data: { pt: { __kind: 'acme.Point', x: 3, y: 4 } } };
1387
- const result = JSON.parse(fmt(entry));
1335
+ const fmt = createJsonLogFormatter(state);
1336
+ const result = JSON.parse(fmt(entryOf(LogLevel.Info, null, { pt: { __kind: 'acme.Point', x: 3, y: 4 } })));
1388
1337
  expect(result.data.pt).toEqual({ serialized: '(3,4)' });
1389
1338
  });
1390
1339
 
1391
1340
  it('preserves values that do not match a registered serializer', () => {
1392
- registerLogSerializer('acme.Known', () => ({ serialized: true }));
1393
- const fmt = createJsonLogFormatter();
1341
+ registerLogSerializer(state, 'acme.Known', () => ({ serialized: true }));
1342
+ const fmt = createJsonLogFormatter(state);
1394
1343
  const data = {
1395
1344
  missingKind: { value: 1 },
1396
1345
  nullValue: null,
@@ -1399,7 +1348,7 @@ describe('registerLogSerializer', () => {
1399
1348
  unknownKind: { __kind: 'acme.Unknown', value: 4 },
1400
1349
  };
1401
1350
 
1402
- const result = JSON.parse(fmt({ channel: null, data, level: LogLevel.Info }));
1351
+ const result = JSON.parse(fmt(entryOf(LogLevel.Info, null, data)));
1403
1352
 
1404
1353
  expect(result.data).toEqual(data);
1405
1354
  });
@@ -1411,16 +1360,16 @@ describe('removeLogSink', () => {
1411
1360
  const sink = (e: Readonly<LogEntry>): void => {
1412
1361
  entries.push({ ...e });
1413
1362
  };
1414
- addLogSink(sink);
1415
- const removed = removeLogSink(sink);
1363
+ addLogSink(state, sink);
1364
+ const removed = removeLogSink(state, sink);
1416
1365
  expect(removed).toBe(true);
1417
- log(LogLevel.Info, 'x');
1366
+ log(state, 0, LogLevel.Info, 'x');
1418
1367
  expect(entries).toHaveLength(0);
1419
1368
  });
1420
1369
 
1421
1370
  it('returns false when the sink was not registered', () => {
1422
1371
  const sink = (): void => {};
1423
- expect(removeLogSink(sink)).toBe(false);
1372
+ expect(removeLogSink(state, sink)).toBe(false);
1424
1373
  });
1425
1374
  });
1426
1375
 
@@ -1456,17 +1405,17 @@ describe('serializeLogError', () => {
1456
1405
  describe('setLogChannelLevel', () => {
1457
1406
  it('suppresses entries below the channel level', () => {
1458
1407
  const { entries } = recordingSink();
1459
- setLogChannelLevel('render', LogLevel.Error);
1460
- log(LogLevel.Info, 'info on render channel', 'render');
1461
- log(LogLevel.Error, 'error on render channel', 'render');
1408
+ setLogChannelLevel(state, 'render', LogLevel.Error);
1409
+ log(state, 0, LogLevel.Info, 'info on render channel', 'render');
1410
+ log(state, 0, LogLevel.Error, 'error on render channel', 'render');
1462
1411
  expect(entries).toHaveLength(1);
1463
1412
  expect(entries[0].level).toBe(LogLevel.Error);
1464
1413
  });
1465
1414
 
1466
1415
  it('does not affect other channels', () => {
1467
1416
  const { entries } = recordingSink();
1468
- setLogChannelLevel('render', LogLevel.Error);
1469
- log(LogLevel.Info, 'other', 'audio');
1417
+ setLogChannelLevel(state, 'render', LogLevel.Error);
1418
+ log(state, 0, LogLevel.Info, 'other', 'audio');
1470
1419
  expect(entries).toHaveLength(1);
1471
1420
  });
1472
1421
  });
@@ -1475,9 +1424,9 @@ describe('setLogConsoleLevel', () => {
1475
1424
  it('raises the threshold so finer levels print a human line', () => {
1476
1425
  vi.spyOn(console, 'debug').mockImplementation(() => {});
1477
1426
  const consoleLog = vi.spyOn(console, 'log').mockImplementation(() => {});
1478
- setLogConsoleLevel(LogLevel.Verbose);
1479
- setLogSink(createConsoleCaptureSink());
1480
- log(LogLevel.Verbose, 'now shown');
1427
+ setLogConsoleLevel(state, LogLevel.Verbose);
1428
+ setLogSink(state, createConsoleCaptureSink(state));
1429
+ log(state, 0, LogLevel.Verbose, 'now shown');
1481
1430
  expect(consoleLog).toHaveBeenCalledTimes(1);
1482
1431
  });
1483
1432
  });
@@ -1485,75 +1434,82 @@ describe('setLogConsoleLevel', () => {
1485
1434
  describe('setLogLevel', () => {
1486
1435
  it('suppresses entries below the global level', () => {
1487
1436
  const { entries } = recordingSink();
1488
- setLogLevel(LogLevel.Error);
1489
- log(LogLevel.Info, 'suppressed');
1490
- log(LogLevel.Error, 'emitted');
1437
+ setLogLevel(state, LogLevel.Error);
1438
+ log(state, 0, LogLevel.Info, 'suppressed');
1439
+ log(state, 0, LogLevel.Error, 'emitted');
1491
1440
  expect(entries).toHaveLength(1);
1492
1441
  expect(entries[0].data).toBe('emitted');
1493
1442
  });
1494
1443
 
1495
1444
  it('LogLevel.None always suppresses (never-emit guard)', () => {
1496
1445
  const { entries } = recordingSink();
1497
- setLogLevel(LogLevel.None);
1498
- log(LogLevel.None, 'should not emit');
1446
+ setLogLevel(state, LogLevel.None);
1447
+ log(state, 0, LogLevel.None, 'should not emit');
1499
1448
  expect(entries).toHaveLength(0);
1500
1449
  });
1501
1450
  });
1502
1451
 
1503
1452
  describe('setLogRedactionPaths', () => {
1504
1453
  it('replaces top-level fields matching a path', () => {
1505
- setLogRedactionPaths(['password']);
1506
- const fmt = createJsonLogFormatter();
1507
- const entry: LogEntry = { level: LogLevel.Info, channel: null, data: { user: 'alice', password: 'secret' } };
1508
- const result = JSON.parse(fmt(entry));
1454
+ setLogRedactionPaths(state, ['password']);
1455
+ const fmt = createJsonLogFormatter(state);
1456
+ const result = JSON.parse(fmt(entryOf(LogLevel.Info, null, { user: 'alice', password: 'secret' })));
1509
1457
  expect(result.data.password).toBe('[REDACTED]');
1510
1458
  expect(result.data.user).toBe('alice');
1511
1459
  });
1512
1460
 
1513
1461
  it('replaces nested fields with dot-notation paths', () => {
1514
- setLogRedactionPaths(['auth.secret']);
1515
- const fmt = createJsonLogFormatter();
1516
- const entry: LogEntry = { level: LogLevel.Info, channel: null, data: { auth: { secret: 'tok', name: 'jwt' } } };
1517
- const result = JSON.parse(fmt(entry));
1462
+ setLogRedactionPaths(state, ['auth.secret']);
1463
+ const fmt = createJsonLogFormatter(state);
1464
+ const result = JSON.parse(fmt(entryOf(LogLevel.Info, null, { auth: { secret: 'tok', name: 'jwt' } })));
1518
1465
  expect(result.data.auth.secret).toBe('[REDACTED]');
1519
1466
  expect(result.data.auth.name).toBe('jwt');
1520
1467
  });
1521
1468
 
1522
1469
  it('does not mutate the original data object (alias-safe)', () => {
1523
- setLogRedactionPaths(['key']);
1470
+ setLogRedactionPaths(state, ['key']);
1524
1471
  const original = { key: 'value', other: 'safe' };
1525
- const entry: LogEntry = { level: LogLevel.Info, channel: null, data: original };
1526
- const fmt = createJsonLogFormatter();
1527
- fmt(entry);
1472
+ const fmt = createJsonLogFormatter(state);
1473
+ fmt(entryOf(LogLevel.Info, null, original));
1528
1474
  // The original object should not be mutated
1529
1475
  expect(original.key).toBe('value');
1530
1476
  });
1531
1477
 
1532
1478
  it('leaves absent and non-record path segments unchanged', () => {
1533
- setLogRedactionPaths(['missing.secret', 'nullValue.secret', 'primitive.secret', 'items.secret']);
1479
+ setLogRedactionPaths(state, ['missing.secret', 'nullValue.secret', 'primitive.secret', 'items.secret']);
1534
1480
  const data = { items: ['secret'], nullValue: null, primitive: 7 };
1535
- const fmt = createJsonLogFormatter();
1481
+ const fmt = createJsonLogFormatter(state);
1536
1482
 
1537
- const result = JSON.parse(fmt({ channel: null, data, level: LogLevel.Info }));
1483
+ const result = JSON.parse(fmt(entryOf(LogLevel.Info, null, data)));
1538
1484
 
1539
1485
  expect(result.data).toEqual(data);
1540
1486
  });
1487
+
1488
+ it('copies the paths so later edits to the input array do not apply', () => {
1489
+ const paths = ['password'];
1490
+ setLogRedactionPaths(state, paths);
1491
+ paths.push('user');
1492
+ const result = JSON.parse(
1493
+ createJsonLogFormatter(state)(entryOf(LogLevel.Info, null, { user: 'alice', password: 'pw' })),
1494
+ );
1495
+ expect(result.data.user).toBe('alice');
1496
+ });
1541
1497
  });
1542
1498
 
1543
1499
  describe('setLogSink', () => {
1544
1500
  it('clears the sink list when passed null', () => {
1545
1501
  const { entries } = recordingSink();
1546
- setLogSink(null);
1547
- log(LogLevel.Info, 'x');
1502
+ setLogSink(state, null);
1503
+ log(state, 0, LogLevel.Info, 'x');
1548
1504
  expect(entries).toHaveLength(0);
1549
1505
  });
1550
1506
 
1551
1507
  it('replaces all existing sinks with the single given sink', () => {
1552
1508
  const a: LogEntry[] = [];
1553
1509
  const b: LogEntry[] = [];
1554
- addLogSink((e) => a.push({ ...e }));
1555
- setLogSink((e) => b.push({ ...e }));
1556
- log(LogLevel.Info, 'x');
1510
+ addLogSink(state, (e) => a.push({ ...e }));
1511
+ setLogSink(state, (e) => b.push({ ...e }));
1512
+ log(state, 0, LogLevel.Info, 'x');
1557
1513
  expect(a).toHaveLength(0);
1558
1514
  expect(b).toHaveLength(1);
1559
1515
  });
@@ -1562,22 +1518,22 @@ describe('setLogSink', () => {
1562
1518
  describe('severity wrapper providers and gates', () => {
1563
1519
  it('does not evaluate any provider when its level is suppressed', () => {
1564
1520
  const { entries } = recordingSink();
1565
- const context = createLogContext('channel');
1521
+ const context = contextOf('channel');
1566
1522
  const providers = Array.from({ length: 12 }, (_, index) => vi.fn(() => `value-${index}`));
1567
- setLogLevel(LogLevel.None);
1568
-
1569
- logAssert(false, providers[0]);
1570
- logDebug(providers[1]);
1571
- logDebugWith(context, providers[2]);
1572
- logError(providers[3]);
1573
- logErrorWith(context, providers[4]);
1574
- logInfo(providers[5]);
1575
- logInfoWith(context, providers[6]);
1576
- logVerbose(providers[7]);
1577
- logVerboseWith(context, providers[8]);
1578
- logWarn(providers[9]);
1579
- logWarnWith(context, providers[10]);
1580
- logWith(context, LogLevel.Info, providers[11]);
1523
+ setLogLevel(state, LogLevel.None);
1524
+
1525
+ logAssert(state, 0, false, providers[0]);
1526
+ logDebug(state, 0, providers[1]);
1527
+ logDebugWith(state, 0, context, providers[2]);
1528
+ logError(state, 0, providers[3]);
1529
+ logErrorWith(state, 0, context, providers[4]);
1530
+ logInfo(state, 0, providers[5]);
1531
+ logInfoWith(state, 0, context, providers[6]);
1532
+ logVerbose(state, 0, providers[7]);
1533
+ logVerboseWith(state, 0, context, providers[8]);
1534
+ logWarn(state, 0, providers[9]);
1535
+ logWarnWith(state, 0, context, providers[10]);
1536
+ logWith(state, 0, context, LogLevel.Info, providers[11]);
1581
1537
 
1582
1538
  for (const provider of providers) expect(provider).not.toHaveBeenCalled();
1583
1539
  expect(entries).toHaveLength(0);
@@ -1585,19 +1541,19 @@ describe('severity wrapper providers and gates', () => {
1585
1541
 
1586
1542
  it('evaluates providers after their level gates pass', () => {
1587
1543
  const { entries } = recordingSink();
1588
- const context = createLogContext('channel');
1544
+ const context = contextOf('channel');
1589
1545
  const providers = Array.from({ length: 10 }, (_, index) => vi.fn(() => `value-${index}`));
1590
1546
 
1591
- logAssert(false, providers[0]);
1592
- logDebugWith(context, providers[1]);
1593
- logError(providers[2]);
1594
- logErrorWith(context, providers[3]);
1595
- logInfo(providers[4]);
1596
- logInfoWith(context, providers[5]);
1597
- logVerbose(providers[6]);
1598
- logVerboseWith(context, providers[7]);
1599
- logWarn(providers[8]);
1600
- logWarnWith(context, providers[9]);
1547
+ logAssert(state, 0, false, providers[0]);
1548
+ logDebugWith(state, 0, context, providers[1]);
1549
+ logError(state, 0, providers[2]);
1550
+ logErrorWith(state, 0, context, providers[3]);
1551
+ logInfo(state, 0, providers[4]);
1552
+ logInfoWith(state, 0, context, providers[5]);
1553
+ logVerbose(state, 0, providers[6]);
1554
+ logVerboseWith(state, 0, context, providers[7]);
1555
+ logWarn(state, 0, providers[8]);
1556
+ logWarnWith(state, 0, context, providers[9]);
1601
1557
 
1602
1558
  for (const provider of providers) expect(provider).toHaveBeenCalledTimes(1);
1603
1559
  expect(entries.map((entry) => (typeof entry.data === 'string' ? entry.data : entry.data.msg))).toEqual(
@@ -1607,28 +1563,17 @@ describe('severity wrapper providers and gates', () => {
1607
1563
  });
1608
1564
 
1609
1565
  describe('startLogTimer', () => {
1610
- it('returns a LogTimer with the given label and channel', () => {
1611
- const timer = startLogTimer('render', 'perf');
1612
- expect(timer.label).toBe('render');
1613
- expect(timer.channel).toBe('perf');
1614
- expect(timer.startedAt).toBeGreaterThanOrEqual(0);
1615
- });
1616
-
1617
- it('falls back to Date.now when performance is unavailable', () => {
1618
- const originalPerformance = globalThis.performance;
1619
- vi.spyOn(Date, 'now').mockReturnValue(1234);
1620
- let startedAt: number;
1621
- Object.defineProperty(globalThis, 'performance', { configurable: true, value: undefined, writable: true });
1622
- try {
1623
- startedAt = startLogTimer('fallback').startedAt;
1624
- } finally {
1625
- Object.defineProperty(globalThis, 'performance', {
1626
- configurable: true,
1627
- value: originalPerformance,
1628
- writable: true,
1629
- });
1630
- }
1631
-
1632
- expect(startedAt!).toBe(1234);
1566
+ it('returns a LogTimer with the given label, channel, and start time', () => {
1567
+ const timer = startLogTimer('render', 'perf', 12.5);
1568
+ expect(timer).toEqual({ label: 'render', channel: 'perf', startedAt: 12.5 });
1569
+ });
1570
+
1571
+ it('records the injected time without reading a clock', () => {
1572
+ const now = vi.spyOn(Date, 'now');
1573
+ const performanceNow = vi.spyOn(performance, 'now');
1574
+
1575
+ expect(startLogTimer('injected', null, 1234).startedAt).toBe(1234);
1576
+ expect(now).not.toHaveBeenCalled();
1577
+ expect(performanceNow).not.toHaveBeenCalled();
1633
1578
  });
1634
1579
  });