@huaqiu/dsh-plugin-log 0.6.23 → 0.6.25

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/runtime.ts ADDED
@@ -0,0 +1,633 @@
1
+ /**
2
+ * Process-wide logging runtime for ONE DSH process.
3
+ *
4
+ * This module is the only place that decides WHERE records go. Plugins never
5
+ * see it: they call `getLogger()` and get a namespaced logger.
6
+ *
7
+ * Startup order (docs/tasks/dsh-plugin-log-isolation.md §4):
8
+ * 1. read the parent logging context from the environment
9
+ * 2. generate `dsh_instance_id` (per LAUNCH, never per plugin)
10
+ * 3. create `<dsh-root>/<dsh_instance_id>/` exclusively
11
+ * 4. write `instance.json` atomically (never overwrite)
12
+ * 5. acquire the OS ownership lock for that directory
13
+ * 6. open `dsh.<date>.log` and replay records buffered during 1–5
14
+ *
15
+ * Steps 1–4 are synchronous so that `logDir()` / `logFilePath()` are correct
16
+ * the instant DSH starts. Step 5 is asynchronous (a socket bind resolves on the
17
+ * event loop), so records emitted in the meantime are buffered — bounded — and
18
+ * replayed after ownership is confirmed. If ownership cannot be established the
19
+ * destination is marked unavailable and the buffer is dropped: there is
20
+ * deliberately no fallback to a shared writable file.
21
+ *
22
+ * ## Why `globalThis`
23
+ *
24
+ * A plugin bundle may inline its own copy of this package, so a module-level
25
+ * singleton would give each copy its own sink, rotation counter and buffer.
26
+ * The state lives on `globalThis` under a `Symbol.for` key, which is a genuine
27
+ * process-wide registry: every copy — bundled, external or duplicated —
28
+ * cooperates on one destination.
29
+ */
30
+ import { existsSync, mkdirSync } from 'node:fs'
31
+ import { join } from 'node:path'
32
+
33
+ import {
34
+ DSH_METADATA_SCHEMA_VERSION,
35
+ FATAL_LOG_FILENAME,
36
+ INSTANCE_METADATA_FILENAME,
37
+ createDshIdentity,
38
+ instanceDirFor,
39
+ readDshInstanceMetadata,
40
+ readDshLogContext,
41
+ type DshInstanceMetadata,
42
+ type DshLogContext,
43
+ } from './identity.js'
44
+ import { acquireDshOwnership, type DshOwnershipHandle } from './ownership.js'
45
+ import {
46
+ DSH_ROTATION,
47
+ DshLogWriter,
48
+ type DshRotationConfig,
49
+ type DshRotationFaults,
50
+ type LoggingHealth,
51
+ } from './rotation.js'
52
+ import { cleanupExpiredDshInstances, recoverDshInstances, reportLegacyPluginLogs } from './recovery.js'
53
+ import { appendDiagnostic, atomicCreateNewFile } from './fs-utils.js'
54
+ import { getLogBaseDir } from './paths.js'
55
+
56
+ const STATE_KEY = Symbol.for('@huaqiu/dsh-plugin-log/runtime')
57
+ const HOST_SINK_KEY = Symbol.for('@huaqiu/dsh-plugin-log/host-sink')
58
+ const STDIO_GUARD_KEY = Symbol.for('@huaqiu/dsh-plugin-log/stdio')
59
+
60
+ /**
61
+ * A sink supplied by the DSH host. When present the package delegates the
62
+ * actual transport (and its lifecycle) to DSH instead of opening its own file
63
+ * — the preferred integration when DSH exposes a native logging service.
64
+ */
65
+ export interface HostLogSink {
66
+ write(line: string): void
67
+ flush?(): Promise<void>
68
+ close?(): void
69
+ }
70
+
71
+ export interface DshLogRuntimeConfig {
72
+ /** Explicit DSH log ROOT. The instance directory is always appended. */
73
+ dshLogRoot?: string
74
+ /** HQ Edge log base override, used when no DSH root is given. */
75
+ baseDir?: string
76
+ /** Test / host injection of the instance id. Production generates one. */
77
+ dshInstanceId?: string
78
+ rotation?: DshRotationConfig
79
+ /** Test-only: skip the OS lock (never in production). */
80
+ skipOwnership?: boolean
81
+ ownershipTimeoutMs?: number
82
+ now?: () => Date
83
+ faults?: DshRotationFaults
84
+ /** Extra structured sink for internal diagnostics (tests). */
85
+ onDiagnostic?: (record: Record<string, unknown>) => void
86
+ }
87
+
88
+ type OwnershipState = 'pending' | 'held' | 'skipped' | 'unavailable'
89
+
90
+ interface DshRuntimeState {
91
+ readonly schema: 2
92
+ config: DshLogRuntimeConfig | null
93
+ context: DshLogContext | null
94
+ identity: DshInstanceMetadata | null
95
+ instanceDir: string | null
96
+ ownership: DshOwnershipHandle | null
97
+ ownershipState: OwnershipState
98
+ ownershipPromise: Promise<void> | null
99
+ writer: DshLogWriter | null
100
+ ready: boolean
101
+ degradedReason: string | null
102
+ pending: string[]
103
+ pendingBytes: number
104
+ droppedBeforeReady: number
105
+ shutdown: boolean
106
+ shutdownPromise: Promise<void> | null
107
+ maintenanceScheduled: boolean
108
+ generation: number
109
+ }
110
+
111
+ const MAX_PENDING_RECORDS = 2_000
112
+ const MAX_PENDING_BYTES = 1024 * 1024
113
+ const DEFAULT_OWNERSHIP_TIMEOUT_MS = 5_000
114
+ const FLUSH_TIMEOUT_MS = 5_000
115
+ const MAINTENANCE_DELAY_MS = 1_500
116
+ const MAINTENANCE_BUDGET_MS = 3_000
117
+ const RETENTION_DAYS = 30
118
+
119
+ function freshState(): DshRuntimeState {
120
+ return {
121
+ schema: 2,
122
+ config: null,
123
+ context: null,
124
+ identity: null,
125
+ instanceDir: null,
126
+ ownership: null,
127
+ ownershipState: 'pending',
128
+ ownershipPromise: null,
129
+ writer: null,
130
+ ready: false,
131
+ degradedReason: null,
132
+ pending: [],
133
+ pendingBytes: 0,
134
+ droppedBeforeReady: 0,
135
+ shutdown: false,
136
+ shutdownPromise: null,
137
+ maintenanceScheduled: false,
138
+ generation: 0,
139
+ }
140
+ }
141
+
142
+ function state(): DshRuntimeState {
143
+ const registry = globalThis as Record<symbol, unknown>
144
+ const existing = registry[STATE_KEY] as DshRuntimeState | undefined
145
+ if (existing && existing.schema === 2) return existing
146
+ const created = freshState()
147
+ registry[STATE_KEY] = created
148
+ return created
149
+ }
150
+
151
+ function hostSink(): HostLogSink | null {
152
+ const registry = globalThis as Record<symbol, unknown>
153
+ return (registry[HOST_SINK_KEY] as HostLogSink | undefined) ?? null
154
+ }
155
+
156
+ /**
157
+ * Installs a DSH-host-provided sink. MUST be called before the first log
158
+ * record: once the package has established its own destination (and taken the
159
+ * ownership lock), silently switching transports would abandon a directory it
160
+ * owns. A late call is ignored and diagnosed rather than throwing.
161
+ */
162
+ export function installHostLogSink(sink: HostLogSink | null): void {
163
+ const registry = globalThis as Record<symbol, unknown>
164
+ if (sink === null) {
165
+ delete registry[HOST_SINK_KEY]
166
+ return
167
+ }
168
+ const s = state()
169
+ if (s.identity !== null) {
170
+ appendDiagnostic(join(s.instanceDir ?? '.', FATAL_LOG_FILENAME), {
171
+ event: 'host-sink-installed-too-late',
172
+ detail: 'installHostLogSink() must be called before the first log record',
173
+ })
174
+ return
175
+ }
176
+ registry[HOST_SINK_KEY] = sink
177
+ }
178
+
179
+ function degraded(reason: string, detail?: string): void {
180
+ const s = state()
181
+ s.degradedReason = reason
182
+ s.ownershipState = 'unavailable'
183
+ if (s.instanceDir && detail) {
184
+ appendDiagnostic(join(s.instanceDir, FATAL_LOG_FILENAME), {
185
+ event: 'logging-degraded',
186
+ reason,
187
+ detail,
188
+ dshInstanceId: s.identity?.dshInstanceId ?? null,
189
+ pid: process.pid,
190
+ })
191
+ }
192
+ }
193
+
194
+ // ── stdio guard ─────────────────────────────────────────────────────────────
195
+
196
+ interface StdioGuard {
197
+ stdout: boolean
198
+ stderr: boolean
199
+ reported: boolean
200
+ }
201
+
202
+ /**
203
+ * DSH's stdout/stderr are pipes owned by HQ Edge. If the parent dies or closes
204
+ * the pipe, writing to it raises EPIPE asynchronously on the stream, which
205
+ * without a listener is an uncaught exception: a logging call would take the
206
+ * DSH process down. Install one `error` listener per stream, mark the stream
207
+ * unusable and stop mirroring to it.
208
+ */
209
+ function installStdioGuard(): StdioGuard {
210
+ const registry = globalThis as Record<symbol, unknown>
211
+ const existing = registry[STDIO_GUARD_KEY] as StdioGuard | undefined
212
+ if (existing) return existing
213
+
214
+ const guard: StdioGuard = { stdout: true, stderr: true, reported: false }
215
+ const attach = (name: 'stdout' | 'stderr', stream: NodeJS.WriteStream | undefined): void => {
216
+ if (!stream || typeof stream.on !== 'function') return
217
+ stream.on('error', (err: unknown) => {
218
+ guard[name] = false
219
+ if (guard.reported) return
220
+ guard.reported = true
221
+ const s = state()
222
+ if (!s.instanceDir) return
223
+ appendDiagnostic(join(s.instanceDir, FATAL_LOG_FILENAME), {
224
+ event: 'stdio-error',
225
+ stream: name,
226
+ code: (err as NodeJS.ErrnoException | undefined)?.code ?? 'UNKNOWN',
227
+ message: err instanceof Error ? err.message : String(err),
228
+ note: 'console mirroring disabled; file logging unaffected',
229
+ })
230
+ })
231
+ }
232
+ attach('stdout', process.stdout)
233
+ attach('stderr', process.stderr)
234
+ registry[STDIO_GUARD_KEY] = guard
235
+ return guard
236
+ }
237
+
238
+ /** True when `name` is still safe to write to. */
239
+ export function isStdioHealthy(name: 'stdout' | 'stderr'): boolean {
240
+ return installStdioGuard()[name]
241
+ }
242
+
243
+ // ── initialization ──────────────────────────────────────────────────────────
244
+
245
+ /**
246
+ * Creates the instance directory and metadata, then starts ownership
247
+ * acquisition in the background. Idempotent: later calls return immediately.
248
+ */
249
+ export function initializeDshRuntime(config: DshLogRuntimeConfig = {}): void {
250
+ const s = state()
251
+ if (s.shutdown) return
252
+ if (s.identity !== null) return
253
+
254
+ s.config = config
255
+ s.generation += 1
256
+ const generation = s.generation
257
+
258
+ const context = readDshLogContext(process.env, {
259
+ dshLogRoot: config.dshLogRoot,
260
+ baseDir: config.baseDir,
261
+ })
262
+ s.context = context
263
+
264
+ // Ensure the root exists before the exclusive per-instance creation, which
265
+ // must fail rather than reuse an existing directory.
266
+ try {
267
+ mkdirSync(context.dshLogRoot, { recursive: true })
268
+ } catch (err) {
269
+ degraded('dsh-log-root-unavailable', String(err))
270
+ return
271
+ }
272
+
273
+ let identity: DshInstanceMetadata | null = null
274
+ let instanceDir: string | null = null
275
+ for (let attempt = 0; attempt < 3 && identity === null; attempt += 1) {
276
+ const candidate = createDshIdentity(context, {
277
+ dshInstanceId: config.dshInstanceId,
278
+ now: config.now?.(),
279
+ })
280
+ const candidateDir = instanceDirFor(candidate)
281
+
282
+ let created = false
283
+ try {
284
+ // Non-recursive on purpose: a UUID collision must be visible, never
285
+ // silently merged.
286
+ mkdirSync(candidateDir)
287
+ created = true
288
+ } catch {
289
+ created = false
290
+ }
291
+
292
+ if (!created) {
293
+ if (!existsSync(candidateDir)) {
294
+ degraded('instance-directory-unavailable', candidateDir)
295
+ return
296
+ }
297
+ // The directory already exists. Adopt it ONLY when its metadata names
298
+ // this exact instance id (a restart of the same logical instance, e.g.
299
+ // a test with a fixed id, or a crashed process whose directory was
300
+ // never cleaned). Ownership is still acquired later: if a live process
301
+ // owns it, the destination degrades instead of sharing the file.
302
+ const existing = readDshInstanceMetadata(candidateDir)
303
+ if (existing !== null && existing.dshInstanceId === candidate.dshInstanceId) {
304
+ identity = candidate
305
+ instanceDir = candidateDir
306
+ break
307
+ }
308
+ if (config.dshInstanceId !== undefined) {
309
+ degraded('instance-directory-collision', candidateDir)
310
+ return
311
+ }
312
+ continue
313
+ }
314
+
315
+ const metadataPath = join(candidateDir, INSTANCE_METADATA_FILENAME)
316
+ const metadata = { ...candidate, schemaVersion: DSH_METADATA_SCHEMA_VERSION }
317
+ if (!atomicCreateNewFile(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`)) {
318
+ degraded('instance-metadata-collision', metadataPath)
319
+ return
320
+ }
321
+ identity = candidate
322
+ instanceDir = candidateDir
323
+ }
324
+
325
+ if (identity === null || instanceDir === null) {
326
+ degraded('instance-identity-unavailable')
327
+ return
328
+ }
329
+
330
+ s.identity = identity
331
+ s.instanceDir = instanceDir
332
+
333
+ // A host-provided sink replaces the file transport entirely (the host owns
334
+ // rotation, ownership and shutdown in that mode).
335
+ if (hostSink() !== null) {
336
+ s.ready = true
337
+ s.ownershipState = 'skipped'
338
+ s.writer = null
339
+ flushPendingIntoHost()
340
+ return
341
+ }
342
+
343
+ const rotation = config.rotation ?? DSH_ROTATION
344
+ const skipOwnership = config.skipOwnership === true
345
+
346
+ s.ownershipPromise = (async () => {
347
+ let handle: DshOwnershipHandle | null = null
348
+ try {
349
+ handle = await acquireDshOwnership(instanceDir as string, identity!.dshInstanceId, {
350
+ diagnostics: true,
351
+ })
352
+ } catch {
353
+ handle = null
354
+ }
355
+ if (s.generation !== generation) {
356
+ handle?.release()
357
+ return
358
+ }
359
+ if (!handle && !skipOwnership) {
360
+ degraded('ownership-unavailable', instanceDir ?? undefined)
361
+ dropPending()
362
+ return
363
+ }
364
+ s.ownership = handle
365
+ s.ownershipState = skipOwnership ? 'skipped' : 'held'
366
+
367
+ const writer = new DshLogWriter({
368
+ dir: instanceDir as string,
369
+ baseName: 'dsh',
370
+ cfg: rotation,
371
+ faults: config.faults,
372
+ now: config.now,
373
+ onDiagnostic: config.onDiagnostic,
374
+ })
375
+ writer.open()
376
+ if (s.shutdown) {
377
+ await writer.close()
378
+ handle?.release()
379
+ return
380
+ }
381
+ s.writer = writer
382
+ s.ready = true
383
+ flushPendingIntoWriter(writer)
384
+ scheduleMaintenance()
385
+ })()
386
+ }
387
+
388
+ function dropPending(): void {
389
+ const s = state()
390
+ s.droppedBeforeReady += s.pending.length
391
+ s.pending = []
392
+ s.pendingBytes = 0
393
+ }
394
+
395
+ function flushPendingIntoWriter(writer: DshLogWriter): void {
396
+ const s = state()
397
+ const pending = s.pending
398
+ s.pending = []
399
+ s.pendingBytes = 0
400
+ for (const line of pending) writer.write(line)
401
+ }
402
+
403
+ function flushPendingIntoHost(): void {
404
+ const sink = hostSink()
405
+ if (!sink) return
406
+ const s = state()
407
+ const pending = s.pending
408
+ s.pending = []
409
+ s.pendingBytes = 0
410
+ for (const line of pending) {
411
+ try {
412
+ sink.write(line)
413
+ } catch {
414
+ s.droppedBeforeReady += 1
415
+ }
416
+ }
417
+ }
418
+
419
+ // ── record intake ───────────────────────────────────────────────────────────
420
+
421
+ /**
422
+ * Accepts one already-serialized JSONL record. Never throws, never blocks.
423
+ * Before the destination is ready the record is buffered (bounded); if the
424
+ * destination is unavailable it is dropped — logging must never fail plugin
425
+ * business logic.
426
+ */
427
+ export function enqueueRecord(line: string): void {
428
+ const s = state()
429
+ if (s.shutdown) return
430
+
431
+ const sink = hostSink()
432
+ if (sink !== null) {
433
+ try {
434
+ sink.write(line)
435
+ } catch {
436
+ s.droppedBeforeReady += 1
437
+ }
438
+ return
439
+ }
440
+
441
+ if (s.writer !== null && s.ready) {
442
+ s.writer.write(line)
443
+ return
444
+ }
445
+ if (s.degradedReason !== null && s.ownershipState === 'unavailable') {
446
+ s.droppedBeforeReady += 1
447
+ return
448
+ }
449
+ const bytes = Buffer.byteLength(line, 'utf8')
450
+ if (s.pending.length >= MAX_PENDING_RECORDS || s.pendingBytes + bytes > MAX_PENDING_BYTES) {
451
+ s.droppedBeforeReady += 1
452
+ return
453
+ }
454
+ s.pending.push(line)
455
+ s.pendingBytes += bytes
456
+ }
457
+
458
+ // ── readiness / health ──────────────────────────────────────────────────────
459
+
460
+ function withTimeout<T>(promise: Promise<T>, ms: number, fallback: T): Promise<T> {
461
+ return Promise.race([promise, new Promise<T>((resolve) => {
462
+ const timer = setTimeout(() => resolve(fallback), ms)
463
+ timer.unref()
464
+ })])
465
+ }
466
+
467
+ /** Resolves when the destination is decided (held, skipped or unavailable). */
468
+ export async function awaitRuntimeReady(timeoutMs = DEFAULT_OWNERSHIP_TIMEOUT_MS): Promise<boolean> {
469
+ const s = state()
470
+ if (s.ready) return true
471
+ if (s.degradedReason !== null) return false
472
+ if (!s.ownershipPromise) return false
473
+ const settled = await withTimeout(
474
+ s.ownershipPromise.then(() => s.ready || s.degradedReason === null),
475
+ timeoutMs,
476
+ false,
477
+ )
478
+ return settled && (s.ready || s.ownershipState === 'skipped')
479
+ }
480
+
481
+ export interface DshRuntimeSnapshot {
482
+ readonly dshInstanceId: string | null
483
+ readonly instanceDir: string | null
484
+ readonly logFile: string | null
485
+ readonly logRoot: string | null
486
+ readonly ready: boolean
487
+ readonly ownership: OwnershipState
488
+ readonly degradedReason: string | null
489
+ readonly droppedBeforeReady: number
490
+ readonly health: LoggingHealth | null
491
+ }
492
+
493
+ export function getRuntimeSnapshot(): DshRuntimeSnapshot {
494
+ const s = state()
495
+ return {
496
+ dshInstanceId: s.identity?.dshInstanceId ?? null,
497
+ instanceDir: s.instanceDir,
498
+ logFile: s.writer?.path ?? null,
499
+ logRoot: s.context?.dshLogRoot ?? null,
500
+ ready: s.ready,
501
+ ownership: s.ownershipState,
502
+ degradedReason: s.degradedReason,
503
+ droppedBeforeReady: s.droppedBeforeReady,
504
+ health: s.writer?.getHealth() ?? null,
505
+ }
506
+ }
507
+
508
+ /** Identity of this DSH process, or null before initialization. */
509
+ export function getDshIdentity(): DshInstanceMetadata | null {
510
+ return state().identity
511
+ }
512
+
513
+ /** Context the log root and parent identities resolved from. */
514
+ export function getDshLogContext(): DshLogContext | null {
515
+ return state().context
516
+ }
517
+
518
+ // ── maintenance ─────────────────────────────────────────────────────────────
519
+
520
+ /**
521
+ * Repairs and prunes HISTORICAL sibling directories. Runs on the serialized
522
+ * writer chain's behalf but touches only directories whose ownership lock is
523
+ * free — i.e. whose DSH process is gone.
524
+ */
525
+ export async function runRuntimeMaintenance(
526
+ options: { timeBudgetMs?: number; retentionDays?: number; minAgeMs?: number } = {},
527
+ ): Promise<void> {
528
+ const s = state()
529
+ if (!s.instanceDir || !s.context) return
530
+ if (s.shutdown) return
531
+ const ownInstanceDir = s.instanceDir
532
+ const instancesRoot = s.context.dshLogRoot
533
+ const report = (record: Record<string, unknown>) => {
534
+ // Diagnostics go to the CURRENT process's own directory, never a
535
+ // historical one that may be deleted by this very pass.
536
+ appendDiagnostic(join(ownInstanceDir, 'maintenance.log'), record)
537
+ }
538
+ try {
539
+ await recoverDshInstances({
540
+ instancesRoot,
541
+ ownInstanceDir,
542
+ timeBudgetMs: options.timeBudgetMs ?? MAINTENANCE_BUDGET_MS,
543
+ minAgeMs: options.minAgeMs,
544
+ report,
545
+ })
546
+ await cleanupExpiredDshInstances({
547
+ instancesRoot,
548
+ ownInstanceDir,
549
+ retentionDays: options.retentionDays ?? RETENTION_DAYS,
550
+ timeBudgetMs: options.timeBudgetMs ?? MAINTENANCE_BUDGET_MS,
551
+ report,
552
+ })
553
+ const legacy = await reportLegacyPluginLogs(getLogBaseDir(s.config?.baseDir))
554
+ if (legacy.files.length > 0) report({ event: 'legacy-plugin-logs', ...legacy })
555
+ } catch {
556
+ /* maintenance must never affect plugin logging */
557
+ }
558
+ }
559
+
560
+ function scheduleMaintenance(): void {
561
+ const s = state()
562
+ if (s.maintenanceScheduled) return
563
+ s.maintenanceScheduled = true
564
+ const timer = setTimeout(() => {
565
+ void runRuntimeMaintenance()
566
+ }, MAINTENANCE_DELAY_MS)
567
+ timer.unref()
568
+ }
569
+
570
+ // ── flush / shutdown ────────────────────────────────────────────────────────
571
+
572
+ /** Waits for everything enqueued so far, bounded. */
573
+ export async function flushRuntime(): Promise<void> {
574
+ const s = state()
575
+ const sink = hostSink()
576
+ if (sink !== null) {
577
+ try {
578
+ await sink.flush?.()
579
+ } catch {
580
+ /* a failed flush must not surface */
581
+ }
582
+ return
583
+ }
584
+ if (s.ownershipPromise) await withTimeout(s.ownershipPromise, FLUSH_TIMEOUT_MS, undefined)
585
+ if (s.writer) await withTimeout(s.writer.flush(), FLUSH_TIMEOUT_MS, undefined)
586
+ }
587
+
588
+ /**
589
+ * Final flush + close + ownership release. Owned by the DSH host only: a
590
+ * plugin unload must never call this, because it would close the destination
591
+ * for every other plugin in the process.
592
+ */
593
+ export async function shutdownRuntime(): Promise<void> {
594
+ const s = state()
595
+ if (s.shutdownPromise) return s.shutdownPromise
596
+ s.shutdown = true
597
+ s.shutdownPromise = (async () => {
598
+ const sink = hostSink()
599
+ if (sink !== null) {
600
+ try {
601
+ await sink.flush?.()
602
+ sink.close?.()
603
+ } catch {
604
+ /* ignore */
605
+ }
606
+ return
607
+ }
608
+ if (s.ownershipPromise) await withTimeout(s.ownershipPromise, FLUSH_TIMEOUT_MS, undefined)
609
+ const writer = s.writer
610
+ s.writer = null
611
+ if (writer) {
612
+ await withTimeout(writer.flush(), FLUSH_TIMEOUT_MS, undefined)
613
+ await withTimeout(writer.close(), FLUSH_TIMEOUT_MS, undefined)
614
+ }
615
+ const ownership = s.ownership
616
+ s.ownership = null
617
+ ownership?.release()
618
+ })()
619
+ return s.shutdownPromise
620
+ }
621
+
622
+ /**
623
+ * Test/teardown helper: shuts the runtime down and forgets all state so a test
624
+ * can re-initialize with different configuration. Never called in production.
625
+ */
626
+ export async function resetRuntime(): Promise<void> {
627
+ const s = state()
628
+ await shutdownRuntime()
629
+ const registry = globalThis as Record<symbol, unknown>
630
+ const fresh = freshState()
631
+ fresh.generation = s.generation + 1
632
+ registry[STATE_KEY] = fresh
633
+ }