@indigoai-us/hq-cloud 6.15.101 → 6.15.102

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/dist/bin/sync-runner-events.test.js +60 -0
  2. package/dist/bin/sync-runner-events.test.js.map +1 -1
  3. package/dist/bin/sync-runner-heap-telemetry.d.ts +344 -0
  4. package/dist/bin/sync-runner-heap-telemetry.d.ts.map +1 -0
  5. package/dist/bin/sync-runner-heap-telemetry.js +550 -0
  6. package/dist/bin/sync-runner-heap-telemetry.js.map +1 -0
  7. package/dist/bin/sync-runner-heap-telemetry.test.d.ts +2 -0
  8. package/dist/bin/sync-runner-heap-telemetry.test.d.ts.map +1 -0
  9. package/dist/bin/sync-runner-heap-telemetry.test.js +697 -0
  10. package/dist/bin/sync-runner-heap-telemetry.test.js.map +1 -0
  11. package/dist/bin/sync-runner-watch-loop.d.ts +29 -0
  12. package/dist/bin/sync-runner-watch-loop.d.ts.map +1 -1
  13. package/dist/bin/sync-runner-watch-loop.js +160 -0
  14. package/dist/bin/sync-runner-watch-loop.js.map +1 -1
  15. package/dist/bin/sync-runner-watch-loop.test.d.ts +2 -0
  16. package/dist/bin/sync-runner-watch-loop.test.d.ts.map +1 -0
  17. package/dist/bin/sync-runner-watch-loop.test.js +62 -0
  18. package/dist/bin/sync-runner-watch-loop.test.js.map +1 -0
  19. package/dist/bin/sync-runner.d.ts +74 -0
  20. package/dist/bin/sync-runner.d.ts.map +1 -1
  21. package/dist/bin/sync-runner.js.map +1 -1
  22. package/dist/sync/event-sync.d.ts +6 -0
  23. package/dist/sync/event-sync.d.ts.map +1 -1
  24. package/dist/sync/event-sync.js +2 -0
  25. package/dist/sync/event-sync.js.map +1 -1
  26. package/dist/watcher.d.ts +28 -2
  27. package/dist/watcher.d.ts.map +1 -1
  28. package/dist/watcher.js +137 -13
  29. package/dist/watcher.js.map +1 -1
  30. package/dist/watcher.test.js +153 -0
  31. package/dist/watcher.test.js.map +1 -1
  32. package/package.json +1 -1
@@ -87,6 +87,66 @@ describe("routeEvents", () => {
87
87
  path: "projects/demo/note.md",
88
88
  });
89
89
  });
90
+ it("routes the diagnostic heap-pressure event to stdout, never the error stream", () => {
91
+ // The heap-pressure crossing is a purely diagnostic signal. It must NOT be
92
+ // in ERROR_TYPES: routing it to stderr would drive the menubar's
93
+ // is_alertable_error path and raise a user-facing sync failure for a signal
94
+ // that describes a healthy, still-running runner approaching its ceiling.
95
+ const { stdout, stderr, streams } = makeStreams();
96
+ routeEvents({
97
+ type: "heap-pressure",
98
+ usedHeapBytes: 1_500_000_000,
99
+ heapLimitBytes: 2_000_000_000,
100
+ usedFraction: 0.75,
101
+ thresholdFraction: 0.75,
102
+ rssBytes: 2_600_000_000,
103
+ externalBytes: 800_000_000,
104
+ uptimeMs: 3_470_000,
105
+ topSites: [
106
+ { site: "publishedContentHashGenerations", count: 12000, growth: 12000 },
107
+ { site: "knownKinds", count: 8000, growth: 3000 },
108
+ ],
109
+ }, streams);
110
+ expect(stderr).toHaveLength(0);
111
+ expect(stdout).toHaveLength(1);
112
+ const event = JSON.parse(stdout[0]);
113
+ expect(event).toMatchObject({ type: "heap-pressure", usedFraction: 0.75 });
114
+ expect(event.topSites[0]).toMatchObject({
115
+ site: "publishedContentHashGenerations",
116
+ growth: 12000,
117
+ });
118
+ });
119
+ it("routes the heap-recycle protocol event to stdout, never the error stream", () => {
120
+ // A deliberate recycle is NOT a crash. Like heap-pressure it must stay off
121
+ // the error channel so the menubar never runs it through is_alertable_error
122
+ // — the runner exits 1 (benign) and the supervisor respawns it.
123
+ const { stdout, stderr, streams } = makeStreams();
124
+ routeEvents({
125
+ type: "heap-recycle",
126
+ usedHeapBytes: 1_700_000_000,
127
+ heapLimitBytes: 2_000_000_000,
128
+ usedFraction: 0.85,
129
+ recycleFraction: 0.78,
130
+ sustainedSamples: 2,
131
+ observedSustainedSamples: 2,
132
+ minUptimeMs: 1_800_000,
133
+ rssBytes: 2_600_000_000,
134
+ externalBytes: 800_000_000,
135
+ uptimeMs: 3_470_000,
136
+ topSites: [
137
+ { site: "publishedContentHashGenerations", count: 12000, growth: 12000 },
138
+ { site: "knownKinds", count: 8000, growth: 3000 },
139
+ ],
140
+ }, streams);
141
+ expect(stderr).toHaveLength(0);
142
+ expect(stdout).toHaveLength(1);
143
+ const event = JSON.parse(stdout[0]);
144
+ expect(event).toMatchObject({
145
+ type: "heap-recycle",
146
+ recycleFraction: 0.78,
147
+ observedSustainedSamples: 2,
148
+ });
149
+ });
90
150
  });
91
151
  describe("emitUncaughtRunnerError (HQ-SYNC-WEB-6)", () => {
92
152
  it("emits a CLASSIFIED error event to stderr — not a silent death — for an uncaught Error", () => {
@@ -1 +1 @@
1
- {"version":3,"file":"sync-runner-events.test.js","sourceRoot":"","sources":["../../src/bin/sync-runner-events.test.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"sync-runner-events.test.js","sourceRoot":"","sources":["../../src/bin/sync-runner-events.test.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,344 @@
1
+ /**
2
+ * First-party heap telemetry for the auto-sync watch runner.
3
+ *
4
+ * The watch runner is a long-lived process whose V8 old space grows across
5
+ * watch cycles until it reaches the desktop-injected `--max-old-space-size`
6
+ * ceiling and V8 aborts with an out-of-memory fatal. Before this module the
7
+ * runner shipped no memory telemetry at all, so nothing in the abort evidence
8
+ * could name which structure held the memory. This module closes that gap: it
9
+ * samples the process heap on a bounded cadence, attributes live entry counts
10
+ * to a fixed set of long-lived structures (the "census"), and — the moment the
11
+ * used heap first crosses a configurable fraction of the ceiling — emits one
12
+ * escalation record ranking those structures by growth since the session began.
13
+ *
14
+ * The whole module is numeric-only and allocation-light by construction:
15
+ *
16
+ * - Every emitted value is a number, and every census site is a FIXED
17
+ * identifier token, never a path/filename/company/message. Records
18
+ * therefore pass the existing telemetry sanitizer unchanged.
19
+ * - The controller retains only the FIRST sample (the growth baseline) and
20
+ * the LATEST sample. It never accumulates history — a memory diagnostic
21
+ * that leaks would regress the very defect it measures.
22
+ * - All readers, timers, and emit callbacks are injected, so the module is
23
+ * driven deterministically by tests with no real allocation, no real heap
24
+ * growth, no wall-clock timing, and no network.
25
+ *
26
+ * Diagnostics must never affect sync: a throwing reader, a faulty census
27
+ * entry, or a rejecting emit callback degrades to silence and never disturbs a
28
+ * watch cycle.
29
+ */
30
+ /** The subset of `v8.getHeapStatistics()` this module reads. */
31
+ export interface HeapStatisticsReading {
32
+ used_heap_size: number;
33
+ total_heap_size: number;
34
+ heap_size_limit: number;
35
+ /** Added in Node 20; may be absent on older runtimes. */
36
+ external_memory?: number;
37
+ }
38
+ /** The subset of `process.memoryUsage()` this module reads. */
39
+ export interface MemoryUsageReading {
40
+ rss: number;
41
+ heapTotal: number;
42
+ heapUsed: number;
43
+ external: number;
44
+ arrayBuffers: number;
45
+ }
46
+ /**
47
+ * Injected readers. Production passes `v8.getHeapStatistics`,
48
+ * `process.memoryUsage`, and `performance.now`; tests pass deterministic fakes.
49
+ */
50
+ export interface HeapReaders {
51
+ getHeapStatistics: () => HeapStatisticsReading;
52
+ memoryUsage: () => MemoryUsageReading;
53
+ /** Monotonic clock in milliseconds (e.g. `performance.now`). */
54
+ monotonicNowMs: () => number;
55
+ }
56
+ /** A census reader returns the live entry count of one long-lived structure. */
57
+ export type CensusReader = () => number;
58
+ export interface CensusSite {
59
+ site: string;
60
+ count: number;
61
+ }
62
+ /**
63
+ * A tiny registry of long-lived structures. Each structure registers once,
64
+ * under a fixed token, a reader that reports only its current entry count. The
65
+ * registry itself is bounded by the fixed token set — registering the same
66
+ * token twice overwrites, so it can never grow without bound.
67
+ */
68
+ export declare class HeapCensus {
69
+ private readonly readers;
70
+ register(token: string, reader: CensusReader): void;
71
+ get siteCount(): number;
72
+ /** Read every registered structure's count. A faulty reader reports 0. */
73
+ snapshot(): CensusSite[];
74
+ }
75
+ /** One flat, numeric-only heap sample plus the census taken with it. */
76
+ export interface RunnerHeapSample {
77
+ uptimeMs: number;
78
+ usedHeapBytes: number;
79
+ totalHeapBytes: number;
80
+ heapLimitBytes: number;
81
+ externalV8Bytes: number;
82
+ rssBytes: number;
83
+ externalBytes: number;
84
+ arrayBuffersBytes: number;
85
+ census: CensusSite[];
86
+ censusTotal: number;
87
+ }
88
+ /** Read the process heap and census once into a numeric-only record. */
89
+ export declare function sampleRunnerHeap(deps: {
90
+ readers: HeapReaders;
91
+ census: HeapCensus;
92
+ sessionStartedAtMs: number;
93
+ }): RunnerHeapSample;
94
+ /**
95
+ * Flatten a sample into numeric telemetry properties. Raw heap figures carry a
96
+ * `heap_`/`rss_`/`external_` prefix; each census site becomes `census_<token>`.
97
+ * Every value is a number, so the record survives the telemetry sanitizer with
98
+ * no weakening of its path/name/message rejection.
99
+ */
100
+ export declare function heapSampleCloudProperties(sample: RunnerHeapSample): Record<string, number>;
101
+ export interface HeapPressureSite {
102
+ site: string;
103
+ count: number;
104
+ growth: number;
105
+ }
106
+ /** The escalation record emitted once when the heap crosses the threshold. */
107
+ export interface HeapPressureRecord {
108
+ usedHeapBytes: number;
109
+ heapLimitBytes: number;
110
+ usedFraction: number;
111
+ thresholdFraction: number;
112
+ rssBytes: number;
113
+ externalBytes: number;
114
+ uptimeMs: number;
115
+ /** Census sites ranked by growth since the session's first sample. */
116
+ topSites: HeapPressureSite[];
117
+ }
118
+ /** Flatten a pressure record into numeric-only telemetry properties. */
119
+ export declare function heapPressureCloudProperties(record: HeapPressureRecord): Record<string, number>;
120
+ /** A compact, numeric-only stderr line that survives when the vault is down. */
121
+ export declare function heapPressureStderrLine(record: HeapPressureRecord): string;
122
+ /**
123
+ * The governor verdict, emitted at most once per session. Where a pressure
124
+ * record is a diagnostic breadcrumb, a recycle is ACTED ON: the watch loop
125
+ * stops admitting new passes, lets the in-flight pass finish, and exits so the
126
+ * desktop supervisor respawns a fresh runner BEFORE V8 aborts the current one.
127
+ *
128
+ * It fires only when ALL of these hold, so a single spike, a young process, or
129
+ * a smaller ceiling can never trip it:
130
+ * - `usedFraction >= recycleFraction` (default 0.78 of the reported heap
131
+ * limit, self-calibrating to whatever `--max-old-space-size` was supplied);
132
+ * - that has held for `sustainedSamples` consecutive samples (default 2);
133
+ * - `uptimeMs >= minUptimeMs` (default 30 min).
134
+ */
135
+ export interface HeapRecycleRecord {
136
+ usedHeapBytes: number;
137
+ heapLimitBytes: number;
138
+ usedFraction: number;
139
+ recycleFraction: number;
140
+ /** Configured number of consecutive over-fraction samples required. */
141
+ sustainedSamples: number;
142
+ /** How many consecutive over-fraction samples were actually observed. */
143
+ observedSustainedSamples: number;
144
+ /** Configured uptime floor (ms) the recycle could not fire before. */
145
+ minUptimeMs: number;
146
+ rssBytes: number;
147
+ externalBytes: number;
148
+ uptimeMs: number;
149
+ /** Census sites ranked by growth since the session's first sample. */
150
+ topSites: HeapPressureSite[];
151
+ }
152
+ /** Flatten a recycle record into numeric-only telemetry properties. */
153
+ export declare function heapRecycleCloudProperties(record: HeapRecycleRecord): Record<string, number>;
154
+ /**
155
+ * A compact, numeric-only stderr line for the recycle verdict. It is worded so
156
+ * it matches NONE of hq-desktop-app's fatal stderr classifiers (no "javascript
157
+ * heap out of memory", "fatal error", "uncaught exception", "panicked at",
158
+ * "assertion failed", a leading "#", the npm "npm error "/"npm ERR! " prefixes,
159
+ * or "ENOSPC"), so a deliberate recycle can never be re-read as a crash by
160
+ * text. `sync-runner-heap-telemetry.test.ts` pins this against that literal
161
+ * marker list.
162
+ */
163
+ export declare function heapRecycleStderrLine(record: HeapRecycleRecord): string;
164
+ export interface RunnerHeapTelemetryOptions {
165
+ readers: HeapReaders;
166
+ census: HeapCensus;
167
+ sessionStartedAtMs: number;
168
+ /** Fraction of `heap_size_limit` that arms the escalation. Default 0.75. */
169
+ pressureThresholdFraction: number;
170
+ /** How many census sites the escalation ranks. Default 8. */
171
+ topSiteCount?: number;
172
+ /**
173
+ * Whether the self-recycling governor is armed. Default true; a kill switch
174
+ * (`HQ_SYNC_RUNNER_HEAP_RECYCLE_ENABLED=0`) sets this false and restores the
175
+ * exact base behaviour — diagnostics only, no recycle verdict ever produced.
176
+ */
177
+ recycleEnabled?: boolean;
178
+ /**
179
+ * Fraction of `heap_size_limit` at or above which a recycle can arm. Default
180
+ * 0.78. Chosen from the measured abort ratio (both production aborts landed
181
+ * at used/declared-ceiling = 0.873): 0.78 x 2048 MB = 1597 MB, plus the
182
+ * worst-case growth accrued while the sustained window confirms (2 samples x
183
+ * 60 s x ~32 MB/min ~= 64 MB) = ~1661 MB, comfortably below the 1788 MB abort
184
+ * point. Fractions are taken against V8's reported `heap_size_limit`, which
185
+ * sits slightly ABOVE the declared `--max-old-space-size`, so the real
186
+ * trigger is if anything lower than this arithmetic — the headroom errs safe.
187
+ */
188
+ recycleFraction?: number;
189
+ /**
190
+ * Consecutive over-fraction samples required before a recycle arms. Default
191
+ * 2, so a single spike can never recycle.
192
+ */
193
+ recycleSustainedSamples?: number;
194
+ /**
195
+ * Process-uptime floor (ms) below which a recycle can never fire, however
196
+ * high the heap climbs. Default 30 min — equal to hq-desktop-app's
197
+ * HEALTHY_RUN_WINDOW — so a recycle can never advance the desktop's 60 s
198
+ * fast-fail counter or its 30-minute slow-death episode streak.
199
+ */
200
+ recycleMinUptimeMs?: number;
201
+ }
202
+ /**
203
+ * Owns the sampling state machine: it keeps the baseline and latest sample, and
204
+ * decides — once per rising crossing of the threshold — when to escalate. The
205
+ * threshold is derived from the injected `heap_size_limit`, so it self-calibrates
206
+ * to whatever `--max-old-space-size` the desktop supplied.
207
+ */
208
+ export declare class RunnerHeapTelemetry {
209
+ private readonly readers;
210
+ private readonly census;
211
+ private readonly sessionStartedAtMs;
212
+ private readonly threshold;
213
+ private readonly topSiteCount;
214
+ private readonly recycleEnabled;
215
+ private readonly recycleFraction;
216
+ private readonly recycleSustainedSamples;
217
+ private readonly recycleMinUptimeMs;
218
+ private baseline;
219
+ private latest;
220
+ private pressureSignalled;
221
+ private recycleSustainedCount;
222
+ private recycleSignalled;
223
+ constructor(options: RunnerHeapTelemetryOptions);
224
+ /**
225
+ * Capture the growth baseline when sampling starts, before the first interval,
226
+ * WITHOUT emitting or arming the pressure signal. Without this, a runner that
227
+ * is already above the threshold at its first scheduled sample would make that
228
+ * same high-water sample its own baseline, so the single crossing record it
229
+ * emits would report zero growth for every site and lose the attribution.
230
+ */
231
+ primeBaseline(): RunnerHeapSample;
232
+ sample(): {
233
+ sample: RunnerHeapSample;
234
+ pressure: HeapPressureRecord | null;
235
+ recycle: HeapRecycleRecord | null;
236
+ };
237
+ /**
238
+ * The governor decision. Returns a record at most once per session, and only
239
+ * when the heap has stayed at or above the recycle fraction for a sustained
240
+ * run of consecutive samples AND the process has outlived the uptime floor.
241
+ * The sustained counter is maintained on every sample so the streak is real
242
+ * consecutive pressure, but the verdict itself is gated on the floor, so a
243
+ * recycle can never fire early however high the heap climbs.
244
+ */
245
+ private detectRecycle;
246
+ private detectPressure;
247
+ private topSitesByGrowth;
248
+ /** Test accessor: the retained growth baseline. */
249
+ get baselineSample(): RunnerHeapSample | null;
250
+ /** Test accessor: the most recent sample. */
251
+ get latestSample(): RunnerHeapSample | null;
252
+ }
253
+ /** Timer seam so tests drive ticks without real wall-clock timers. */
254
+ export interface IntervalScheduler {
255
+ setInterval: (handler: () => void, ms: number) => IntervalHandle;
256
+ clearInterval: (handle: IntervalHandle) => void;
257
+ }
258
+ export interface IntervalHandle {
259
+ unref?: () => void;
260
+ }
261
+ export interface RunnerHeapSamplingOptions extends RunnerHeapTelemetryOptions {
262
+ intervalMs: number;
263
+ onSample: (sample: RunnerHeapSample) => void;
264
+ onPressure: (record: HeapPressureRecord) => void;
265
+ /**
266
+ * Called at most once, when the governor decides the process should recycle.
267
+ * Optional so the diagnostics-only wiring (and every existing caller) needs
268
+ * no change; a faulty callback is swallowed exactly like the others.
269
+ */
270
+ onRecycle?: (record: HeapRecycleRecord) => void;
271
+ scheduler?: IntervalScheduler;
272
+ log?: (message: string) => void;
273
+ }
274
+ export interface RunnerHeapSamplingHandle {
275
+ stop: () => void;
276
+ readonly telemetry: RunnerHeapTelemetry;
277
+ }
278
+ /**
279
+ * Start periodic sampling. The timer is `unref`'d so it can never hold the
280
+ * process open, and `stop()` clears it on every shutdown path. Each tick — and
281
+ * every emit callback it drives — is wrapped so a fault degrades to silence and
282
+ * never affects the watch cycle.
283
+ */
284
+ export declare function startRunnerHeapSampling(options: RunnerHeapSamplingOptions): RunnerHeapSamplingHandle;
285
+ /** Env knob names, exported so the runner and its tests agree on the strings. */
286
+ export declare const HEAP_SAMPLE_INTERVAL_ENV = "HQ_SYNC_RUNNER_HEAP_SAMPLE_MS";
287
+ export declare const HEAP_PRESSURE_FRACTION_ENV = "HQ_SYNC_RUNNER_HEAP_PRESSURE_FRACTION";
288
+ export declare const HEAP_RECYCLE_ENABLED_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_ENABLED";
289
+ export declare const HEAP_RECYCLE_FRACTION_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_FRACTION";
290
+ export declare const HEAP_RECYCLE_SUSTAINED_SAMPLES_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_SUSTAINED_SAMPLES";
291
+ export declare const HEAP_RECYCLE_MIN_UPTIME_MS_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_MIN_UPTIME_MS";
292
+ export declare const DEFAULT_HEAP_SAMPLE_INTERVAL_MS = 60000;
293
+ export declare const DEFAULT_HEAP_PRESSURE_FRACTION = 0.75;
294
+ export declare const DEFAULT_HEAP_RECYCLE_FRACTION = 0.78;
295
+ export declare const DEFAULT_HEAP_RECYCLE_SUSTAINED_SAMPLES = 2;
296
+ export declare const DEFAULT_HEAP_RECYCLE_MIN_UPTIME_MS: number;
297
+ /**
298
+ * Parse the sampling-interval env knob (whole milliseconds). Rejects the ENTIRE
299
+ * string: a value like "60s" must fall back to the default, not silently parse
300
+ * to a 60 ms interval that would fire ~17 samples/second. `Number.parseInt`
301
+ * accepts a numeric prefix, so it is deliberately NOT used here.
302
+ */
303
+ export declare function resolveHeapSampleIntervalMs(raw: string | undefined): number;
304
+ /**
305
+ * Parse the pressure-fraction env knob; falls back to the default on garbage.
306
+ * Rejects the entire string (e.g. "0.5x" falls back) rather than accepting a
307
+ * numeric prefix.
308
+ */
309
+ export declare function resolveHeapPressureFraction(raw: string | undefined): number;
310
+ /**
311
+ * The governor kill switch. The recycle is ON by default; it is disabled ONLY
312
+ * by an explicit, whole-string off value ("0", "false", "no", "off",
313
+ * case-insensitive). Any other value — including garbage — keeps the governor
314
+ * armed, so a typo can never silently disable crash protection.
315
+ */
316
+ export declare function resolveHeapRecycleEnabled(raw: string | undefined): boolean;
317
+ /**
318
+ * Parse the recycle-fraction knob; falls back to the default (0.78) on garbage
319
+ * or out-of-range input. Rejects the entire string (e.g. "0.8x" falls back)
320
+ * rather than accepting a numeric prefix.
321
+ */
322
+ export declare function resolveHeapRecycleFraction(raw: string | undefined): number;
323
+ /**
324
+ * Parse the sustained-samples knob (a whole count >= 1). Falls back to the
325
+ * default (2) on garbage, 0, or a non-integer — a degenerate 0 would let a
326
+ * single spike recycle, exactly what the sustained requirement exists to
327
+ * prevent, so it is refused rather than honoured.
328
+ */
329
+ export declare function resolveHeapRecycleSustainedSamples(raw: string | undefined): number;
330
+ /**
331
+ * Parse the minimum-uptime-floor knob (whole milliseconds, >= 0). Unlike the
332
+ * sample-interval knob, 0 is a VALID value here — it disables the floor, which
333
+ * the deterministic tests rely on — so only a non-integer or negative value
334
+ * falls back to the 30-minute default.
335
+ */
336
+ export declare function resolveHeapRecycleMinUptimeMs(raw: string | undefined): number;
337
+ /**
338
+ * Production readers over the real runtime. Kept here so the wiring site stays
339
+ * a one-liner and the `v8` import lives in exactly one place.
340
+ */
341
+ export declare function nodeHeapReaders(v8: {
342
+ getHeapStatistics: () => HeapStatisticsReading;
343
+ }): HeapReaders;
344
+ //# sourceMappingURL=sync-runner-heap-telemetry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sync-runner-heap-telemetry.d.ts","sourceRoot":"","sources":["../../src/bin/sync-runner-heap-telemetry.ts"],"names":[],"mappings":"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"}