@hydranium/core 1.0.0-next.10

package/lib/node/profile-capture.js

@@ -0,0 +1,315 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+/*
+ * Node-only sampled-profile capture: CPU + allocation over a window (one
+ * `node:inspector` session), plus GC and event-loop delay from
+ * `node:perf_hooks`, and an optional retained heap snapshot. Everything is
+ * default-off and singleton-guarded — the write returns one large JSON object
+ * and briefly blocks the event loop, so nothing here is ever auto-triggered.
+ * The mechanical, process-level counterpart to the protocol's in-code
+ * `ProfileSession` (aggregate self-time spans).
+ */
+import { Format } from '@hydranium/protocol';
+import * as fs from 'node:fs';
+import { Session } from 'node:inspector';
+import { constants, monitorEventLoopDelay, PerformanceObserver, performance } from 'node:perf_hooks';
+import { snapshotFilePath, writeHeapSnapshotToDir } from './process-memory.js';
+export const DEFAULT_CPU_INTERVAL_MICROS = 1000;
+export const DEFAULT_ALLOCATION_INTERVAL_BYTES = 32768;
+/** V8 GC-kind flag → readable name; unknown flags fall back to the number as a string. */
+const GC_KIND_NAMES = {
+    [constants.NODE_PERFORMANCE_GC_MINOR]: 'scavenge',
+    [constants.NODE_PERFORMANCE_GC_MAJOR]: 'mark-sweep-compact',
+    [constants.NODE_PERFORMANCE_GC_INCREMENTAL]: 'incremental-marking',
+    [constants.NODE_PERFORMANCE_GC_WEAKCB]: 'weak-callbacks'
+};
+/**
+ * Tally GC pauses by kind, mapping V8's numeric kind flag to a readable name.
+ * Pure — the timing-dependent capture feeds it the entries.
+ */
+export function summarizeGc(entries) {
+    const byKind = {};
+    let totalPauseMs = 0;
+    for (const { kind, durationMs } of entries) {
+        const name = GC_KIND_NAMES[kind] ?? String(kind);
+        const bucket = (byKind[name] ??= { count: 0, pauseMs: 0 });
+        bucket.count += 1;
+        bucket.pauseMs += durationMs;
+        totalPauseMs += durationMs;
+    }
+    return { count: entries.length, totalPauseMs, byKind };
+}
+/**
+ * Convert an event-loop-delay histogram (nanoseconds) to a millisecond summary,
+ * or `undefined` when the histogram recorded nothing (a purely synchronous
+ * window never lets the sampler tick, leaving `mean === NaN`). Pure.
+ */
+export function summarizeEventLoopDelay(histogram) {
+    if (histogram.count === 0 || !Number.isFinite(histogram.mean)) {
+        return undefined;
+    }
+    const toMs = (nanos) => nanos / 1e6;
+    return {
+        meanMs: toMs(histogram.mean),
+        p50Ms: toMs(histogram.percentile(50)),
+        p99Ms: toMs(histogram.percentile(99)),
+        maxMs: toMs(histogram.max)
+    };
+}
+/** A byte delta with an explicit sign (`Format.bytes` alone drops the sign of a shrink). */
+function signedBytes(bytes) {
+    return `${bytes < 0 ? '-' : '+'}${Format.bytes(Math.abs(bytes))}`;
+}
+/**
+ * Render a {@link ProfileReport} as a compact multi-line block for a log line or a
+ * command channel — the sampled-profile counterpart to `formatProcessMemory`.
+ * Absent dimensions (no gc/eld capture, no written artefacts) are simply omitted.
+ */
+export function formatProfileReport(report, label = 'Profile report') {
+    const lines = [
+        `${label}:`,
+        `  duration    ${Format.elapsed(report.durationMs)}`,
+        `  cpu usage   user ${Math.round(report.cpuUsage.userMs)}ms / system ${Math.round(report.cpuUsage.systemMs)}ms`,
+        `  memory Δ    rss ${signedBytes(report.memoryDelta.rssBytes)}, heapUsed ${signedBytes(report.memoryDelta.heapUsedBytes)}`
+    ];
+    if (report.gc) {
+        const byKind = Object.entries(report.gc.byKind).map(([name, { count, pauseMs }]) => `${name} ×${count} ${Math.round(pauseMs)}ms`);
+        const detail = byKind.length > 0 ? ` — ${byKind.join(', ')}` : '';
+        lines.push(`  gc          ${report.gc.count} pauses, ${Math.round(report.gc.totalPauseMs)}ms total${detail}`);
+    }
+    if (report.eventLoopDelay) {
+        const { meanMs, p50Ms, p99Ms, maxMs } = report.eventLoopDelay;
+        lines.push(`  event loop  mean ${meanMs.toFixed(1)}ms / p50 ${p50Ms.toFixed(1)}ms / p99 ${p99Ms.toFixed(1)}ms / max ${maxMs.toFixed(1)}ms`);
+    }
+    if (report.cpuProfilePath) {
+        lines.push(`  cpu profile ${report.cpuProfilePath}`);
+    }
+    if (report.allocationProfilePath) {
+        lines.push(`  alloc prof  ${report.allocationProfilePath}`);
+    }
+    if (report.heapSnapshotPath) {
+        lines.push(`  heap snap   ${report.heapSnapshotPath}`);
+    }
+    return lines.join('\n');
+}
+function post(session, method, params = {}) {
+    return new Promise((resolve, reject) => {
+        session.post(method, params, (error, result) => (error ? reject(error) : resolve(result)));
+    });
+}
+function toGcEntry(entry) {
+    // `detail` carries the GC kind at runtime but is absent from this @types/node's PerformanceEntry.
+    const detail = entry.detail;
+    return { kind: detail?.kind ?? 0, durationMs: entry.duration };
+}
+/** The one active capture, if any — a single inspector session per process. */
+let active;
+/**
+ * A windowed, sampled profile of the current process. Start it, run the workload,
+ * stop it to get artefact paths + a summary. Singleton-guarded (one inspector
+ * session at a time); prefer {@link profileWorkload} for the common wrap-a-block case.
+ */
+export class ProfileCapture {
+    options;
+    startedAt = 0;
+    startCpu = { user: 0, system: 0 };
+    startMem = process.memoryUsage();
+    session;
+    histogram;
+    gcObserver;
+    gcEntries = [];
+    constructor(options) {
+        this.options = options;
+    }
+    static isActive() {
+        return active !== undefined;
+    }
+    static async start(options) {
+        if (active) {
+            throw new Error('A ProfileCapture is already active; stop it before starting another.');
+        }
+        const capture = new ProfileCapture(options);
+        active = capture;
+        try {
+            await capture.begin();
+        }
+        catch (error) {
+            // begin() may have connected the inspector session / started a sampler
+            // before throwing; tear it all down (and clear the singleton) so a failed
+            // start neither leaks a live session nor lets the next start build a second.
+            capture.teardown();
+            throw error;
+        }
+        return capture;
+    }
+    async begin() {
+        this.startedAt = performance.now();
+        this.startCpu = process.cpuUsage();
+        this.startMem = process.memoryUsage();
+        if (this.options.cpu || this.options.allocation) {
+            const session = new Session();
+            session.connect();
+            this.session = session;
+            if (this.options.cpu) {
+                await post(session, 'Profiler.enable');
+                await post(session, 'Profiler.setSamplingInterval', {
+                    interval: this.options.cpuIntervalMicros ?? DEFAULT_CPU_INTERVAL_MICROS
+                });
+                await post(session, 'Profiler.start');
+            }
+            if (this.options.allocation) {
+                await post(session, 'HeapProfiler.enable');
+                await post(session, 'HeapProfiler.startSampling', {
+                    samplingInterval: this.options.allocationIntervalBytes ?? DEFAULT_ALLOCATION_INTERVAL_BYTES
+                });
+            }
+        }
+        if (this.options.gc) {
+            this.gcEntries = [];
+            this.gcObserver = new PerformanceObserver(list => {
+                for (const entry of list.getEntries()) {
+                    this.gcEntries.push(toGcEntry(entry));
+                }
+            });
+            this.gcObserver.observe({ entryTypes: ['gc'] });
+        }
+        if (this.options.eventLoopDelay) {
+            this.histogram = monitorEventLoopDelay({ resolution: 10 });
+            this.histogram.enable();
+        }
+    }
+    async stop(directory, label) {
+        if (active !== this) {
+            throw new Error('ProfileCapture.stop called on an inactive capture.');
+        }
+        const durationMs = performance.now() - this.startedAt;
+        // Sample cpu + memory at the workload boundary (alongside durationMs), NOT
+        // after teardown: the synchronous profile write inflates RSS and the heap
+        // snapshot forces a full GC, so a post-teardown read would fold the
+        // profiler's own cost into the deltas meant to frame the profiled window.
+        const cpu = process.cpuUsage(this.startCpu);
+        const mem = process.memoryUsage();
+        // Everything below can throw — a `post` can reject on a dropped session, and
+        // the synchronous profile write can fail on ENOSPC/EACCES. Release the
+        // inspector session, the perf_hooks observers and the singleton in `finally`
+        // regardless, so a failed stop() never leaks a live sampler or wedges the
+        // process-wide `active` guard against every future capture.
+        try {
+            // Create the target directory up front so the profile files land there
+            // rather than scattering to os.tmpdir() via snapshotFilePath's fallback,
+            // and so a caller writing a summary beside them finds the directory.
+            if (directory) {
+                fs.mkdirSync(directory, { recursive: true });
+            }
+            // Stop BOTH inspector samplers before serializing anything: writing the CPU
+            // profile allocates, and a still-running allocation sampler would record that
+            // write as if it were the profiled program's work.
+            let cpuProfile;
+            if (this.options.cpu && this.session) {
+                cpuProfile = (await post(this.session, 'Profiler.stop')).profile;
+                await post(this.session, 'Profiler.disable');
+            }
+            let allocationProfile;
+            if (this.options.allocation && this.session) {
+                allocationProfile = (await post(this.session, 'HeapProfiler.stopSampling')).profile;
+                await post(this.session, 'HeapProfiler.disable');
+            }
+            // GC + event-loop delay come from perf_hooks, independent of the samplers.
+            let gc;
+            if (this.gcObserver) {
+                await new Promise(resolve => setImmediate(resolve));
+                for (const entry of this.gcObserver.takeRecords()) {
+                    this.gcEntries.push(toGcEntry(entry));
+                }
+                gc = summarizeGc(this.gcEntries);
+            }
+            let eventLoopDelay;
+            if (this.histogram) {
+                eventLoopDelay = summarizeEventLoopDelay(this.histogram);
+            }
+            // Serialize now that no sampler is running.
+            const cpuProfilePath = cpuProfile !== undefined ? this.writeProfileFile(cpuProfile, directory, label, 'server-cpu', 'cpuprofile') : undefined;
+            const allocationProfilePath = allocationProfile !== undefined
+                ? this.writeProfileFile(allocationProfile, directory, label, 'server-alloc', 'heapprofile')
+                : undefined;
+            const heapSnapshotPath = this.options.heapSnapshot ? writeHeapSnapshotToDir(directory, label) : undefined;
+            return {
+                durationMs,
+                cpuProfilePath,
+                allocationProfilePath,
+                heapSnapshotPath,
+                gc,
+                eventLoopDelay,
+                cpuUsage: { userMs: cpu.user / 1000, systemMs: cpu.system / 1000 },
+                memoryDelta: { rssBytes: mem.rss - this.startMem.rss, heapUsedBytes: mem.heapUsed - this.startMem.heapUsed }
+            };
+        }
+        finally {
+            this.teardown();
+        }
+    }
+    /**
+     * Release the inspector session, perf_hooks observers and the process-wide
+     * singleton. Each disposal is best-effort so one failure cannot skip the rest
+     * (or mask the error that triggered teardown), and nulling the handles makes a
+     * repeat teardown a no-op.
+     */
+    teardown() {
+        try {
+            this.gcObserver?.disconnect();
+        }
+        catch {
+            // best effort — the observer may already be gone
+        }
+        try {
+            this.histogram?.disable();
+        }
+        catch {
+            // best effort
+        }
+        try {
+            this.session?.disconnect();
+        }
+        catch {
+            // best effort — the session may already be disconnected
+        }
+        this.gcObserver = undefined;
+        this.histogram = undefined;
+        this.session = undefined;
+        active = undefined;
+    }
+    writeProfileFile(profile, directory, label, prefix, ext) {
+        const filePath = snapshotFilePath(directory, label, prefix, ext);
+        // Synchronous stringify+write of a large object briefly blocks the loop and
+        // inflates RSS — acceptable because capture is opt-in and never auto-run.
+        fs.writeFileSync(filePath, JSON.stringify(profile));
+        return filePath;
+    }
+}
+/**
+ * Capture a subset of dimensions around an arbitrary async block — the harness /
+ * bench / CLI entry. Always releases the singleton session, even if {@link run}
+ * throws (the error propagates). Writes profile files to `options.directory`.
+ */
+export async function profileWorkload(options, run) {
+    const capture = await ProfileCapture.start(options);
+    const label = options.label ?? 'workload';
+    try {
+        const result = await run();
+        const report = await capture.stop(options.directory, label);
+        return { result, report };
+    }
+    catch (error) {
+        if (ProfileCapture.isActive()) {
+            await capture.stop(options.directory, label).catch(() => undefined);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=profile-capture.js.map

package/lib/node/profile-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-capture.js","sourceRoot":"","sources":["../../src/node/profile-capture.ts"],"names":[],"mappings":"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"}

package/lib/node/profile-digest.d.ts

@@ -0,0 +1,49 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export declare const DEFAULT_DIGEST_TOP_N = 15;
+/** A V8 profile call frame (the subset the digests read). */
+export interface DigestCallFrame {
+    functionName: string;
+    url: string;
+    lineNumber: number;
+}
+/** A V8 CPU profile (`Profiler.stop` output — the subset the digest reads). */
+export interface CpuProfile {
+    nodes: {
+        id: number;
+        callFrame: DigestCallFrame;
+    }[];
+    samples: number[];
+    timeDeltas: number[];
+}
+/** A node of a V8 sampling-heap allocation profile. */
+export interface AllocationNode {
+    callFrame: DigestCallFrame;
+    selfSize: number;
+    children?: AllocationNode[];
+}
+/** A V8 sampling-heap allocation profile (`HeapProfiler.stopSampling` output). */
+export interface AllocationProfile {
+    head: AllocationNode;
+}
+export interface DigestOptions {
+    /** How many functions to list (default {@link DEFAULT_DIGEST_TOP_N}). */
+    topN?: number;
+}
+/**
+ * Top-N functions by CPU self-time, aggregated by call frame. Each `timeDeltas[i]`
+ * (the interval preceding sample `i`) is charged to the frame sampled at `i`, which
+ * preserves the total sampled time but attributes an interval to the sample at its
+ * end rather than DevTools' preceding-sample convention — fine for an approximate
+ * top-N ranking, but expect minor per-frame differences from the DevTools view.
+ */
+export declare function digestCpuProfile(profile: CpuProfile, options?: DigestOptions): string;
+/** Top-N functions by allocation self-size, walking the sampling-heap tree and aggregating by call frame. */
+export declare function digestAllocationProfile(profile: AllocationProfile, options?: DigestOptions): string;
+//# sourceMappingURL=profile-digest.d.ts.map

package/lib/node/profile-digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-digest.d.ts","sourceRoot":"","sources":["../../src/node/profile-digest.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAalF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACrB;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACxB,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,eAAe,CAAA;KAAE,EAAE,CAAC;IACpD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC5B,SAAS,EAAE,eAAe,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,kFAAkF;AAClF,MAAM,WAAW,iBAAiB;IAC/B,IAAI,EAAE,cAAc,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC3B,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;CAChB;AAyBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAazF;AAED,6GAA6G;AAC7G,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAYvG"}

package/lib/node/profile-digest.js

@@ -0,0 +1,74 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+/*
+ * Compact, token-sized top-N text digests of the V8 sampled profiles a
+ * ProfileCapture produces — the entry point a Claude skill reads instead of the
+ * large raw profile JSON. Dependency-free top-N aggregation by design: the raw
+ * `.cpuprofile` / `.heapprofile` are still emitted for the human DevTools path
+ * (flamegraphs, drill-down); this only derives the "where did the time / bytes
+ * go" summary, which is a self-time / self-size sum a skill can act on.
+ */
+import { Format } from '@hydranium/protocol';
+export const DEFAULT_DIGEST_TOP_N = 15;
+function basename(url) {
+    if (!url) {
+        return 'native';
+    }
+    return url.split(/[/\\]/).pop() || url;
+}
+function frameKey(frame) {
+    return `${frame.functionName || '(anonymous)'} (${basename(frame.url)}:${frame.lineNumber})`;
+}
+/** Render a ranked "self-metric by function" digest: the shared shape of both profile digests. */
+function renderRanked(header, totals, topN, format) {
+    const total = [...totals.values()].reduce((sum, value) => sum + value, 0);
+    const rows = [...totals.entries()].sort((a, b) => b[1] - a[1]).slice(0, topN);
+    const lines = [`${header} — top ${rows.length} of ${totals.size} functions (${format(total)} sampled)`];
+    for (const [key, value] of rows) {
+        const percent = total > 0 ? (value / total) * 100 : 0;
+        lines.push(`  ${format(value).padStart(10)}  ${percent.toFixed(1).padStart(5)}%  ${key}`);
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * Top-N functions by CPU self-time, aggregated by call frame. Each `timeDeltas[i]`
+ * (the interval preceding sample `i`) is charged to the frame sampled at `i`, which
+ * preserves the total sampled time but attributes an interval to the sample at its
+ * end rather than DevTools' preceding-sample convention — fine for an approximate
+ * top-N ranking, but expect minor per-frame differences from the DevTools view.
+ */
+export function digestCpuProfile(profile, options = {}) {
+    const frameById = new Map();
+    for (const node of profile.nodes) {
+        frameById.set(node.id, node.callFrame);
+    }
+    const microsByFrame = new Map();
+    profile.samples.forEach((nodeId, index) => {
+        const frame = frameById.get(nodeId);
+        if (frame) {
+            microsByFrame.set(frameKey(frame), (microsByFrame.get(frameKey(frame)) ?? 0) + (profile.timeDeltas[index] ?? 0));
+        }
+    });
+    return renderRanked('CPU self-time', microsByFrame, options.topN ?? DEFAULT_DIGEST_TOP_N, micros => `${(micros / 1000).toFixed(1)}ms`);
+}
+/** Top-N functions by allocation self-size, walking the sampling-heap tree and aggregating by call frame. */
+export function digestAllocationProfile(profile, options = {}) {
+    const bytesByFrame = new Map();
+    const visit = (node) => {
+        if (node.selfSize > 0) {
+            bytesByFrame.set(frameKey(node.callFrame), (bytesByFrame.get(frameKey(node.callFrame)) ?? 0) + node.selfSize);
+        }
+        for (const child of node.children ?? []) {
+            visit(child);
+        }
+    };
+    visit(profile.head);
+    return renderRanked('Allocation', bytesByFrame, options.topN ?? DEFAULT_DIGEST_TOP_N, bytes => Format.bytes(bytes));
+}
+//# sourceMappingURL=profile-digest.js.map

package/lib/node/profile-digest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-digest.js","sourceRoot":"","sources":["../../src/node/profile-digest.ts"],"names":[],"mappings":"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"}

package/lib/node/profiling-run.d.ts

@@ -0,0 +1,80 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { PROFILING_SCHEMA_VERSION, type LatencyCollector, type ProfilingArtifact, type ProfilingArtifactKind, type ProfilingEnvironment, type ProfilingManifest } from '@hydranium/protocol';
+import { type ProfileCaptureOptions, type ProfileReport } from './profile-capture.js';
+export { PROFILING_SCHEMA_VERSION };
+export type { ProfilingArtifact, ProfilingEnvironment, ProfilingManifest };
+/** Options for a {@link ProfilingRun}. Environment fields are injectable so a run is reproducible in tests. */
+export interface ProfilingRunOptions {
+    /** Parent directory for the session folder; falls back to the OS temp dir when missing. */
+    directory?: string;
+    /** Session id / folder name; defaults to `profiling-<timestamp>`. */
+    sessionId?: string;
+    /** `harness` (default) for a headless run, `app` for a real deployment. */
+    mode?: 'harness' | 'app';
+    /** Override the cgroup auto-detection (mainly for tests). */
+    container?: boolean;
+    commit?: string;
+    workspace?: string;
+    /** Which dimensions each window captures (default-off, per {@link ProfileCaptureOptions}). */
+    capture?: ProfileCaptureOptions;
+    /**
+     * Optional latency collector. When present, {@link ProfilingRun.finish} writes
+     * its report to `server-latency.json` and records a `server-latency` manifest artefact. A
+     * head feeds it via the RPC binding / `instrumentLspConnection`; a pure
+     * headless build with no request traffic leaves it empty.
+     */
+    latency?: LatencyCollector;
+}
+/**
+ * A profiling session: create it, run one or more named windows through it, then
+ * {@link finish} to write `server-summary.json` + `manifest.json` and get the manifest.
+ * Windows run sequentially (the underlying capture is a single inspector session).
+ */
+export declare class ProfilingRun {
+    protected readonly options: ProfilingRunOptions;
+    readonly directory: string;
+    protected readonly sessionId: string;
+    protected readonly reports: Record<string, ProfileReport>;
+    protected readonly artifacts: ProfilingArtifact[];
+    protected readonly windows: {
+        label: string;
+        ms: number;
+    }[];
+    protected finished: boolean;
+    /** The `HYDRANIUM_LOG_FILE` value seen before this run pointed it at the session (restored on {@link finish}). */
+    protected readonly previousLogFileEnv?: string;
+    /** Absolute path of the session's teed server log. */
+    readonly serverLogPath: string;
+    protected constructor(options: ProfilingRunOptions, directory: string, sessionId: string);
+    static start(options?: ProfilingRunOptions): Promise<ProfilingRun>;
+    /**
+     * Write an already-collected artefact (e.g. `server-ast.json`,
+     * `server-memory-report.json`) into the session directory and record it in the
+     * manifest. For non-profile inputs a head/harness already has in hand.
+     */
+    attach(kind: ProfilingArtifactKind, filename: string, data: unknown): void;
+    /** Capture {@link run} as a named window, recording its artefacts + duration. Returns the block's result. */
+    window<T>(label: string, run: () => Promise<T>): Promise<T>;
+    /** Build the artefact entry, emitting a `<profile>.txt` digest beside the profile; a digest failure is non-fatal. */
+    protected artifactWithDigest(kind: ProfilingArtifactKind, file: string, window: string, digest: (raw: unknown) => string): ProfilingArtifact;
+    /** Write `server-summary.json` + `manifest.json` into the session directory and return the manifest. */
+    finish(): Promise<ProfilingManifest>;
+}
+/**
+ * Merge one window's {@link ProfileReport} into `<directory>/server-summary.json`
+ * (read-modify-write, keyed by window label). Lets the interactive / RPC capture path
+ * — which stops a single window at a time via the data-server `stopProfiling`, with no
+ * {@link ProfilingRun} to collect the reports — accrue the same `server-summary`
+ * artefact the headless {@link ProfilingRun.finish} writes in one pass. An empty label
+ * is keyed `app`; a malformed or absent existing file is treated as empty. Creates the
+ * directory if needed, so a caller-supplied path that does not yet exist does not throw.
+ */
+export declare function recordServerSummaryEntry(directory: string, label: string, report: ProfileReport): void;
+//# sourceMappingURL=profiling-run.d.ts.map

package/lib/node/profiling-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiling-run.d.ts","sourceRoot":"","sources":["../../src/node/profiling-run.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAYlF,OAAO,EAEJ,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACxB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EAAmB,KAAK,qBAAqB,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAMvG,OAAO,EAAE,wBAAwB,EAAE,CAAC;AACpC,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,CAAC;AAE3E,+GAA+G;AAC/G,MAAM,WAAW,mBAAmB;IACjC,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IACzB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAOD;;;;GAIG;AACH,qBAAa,YAAY;IAanB,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,mBAAmB;IAZlD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IACrC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAM;IAC/D,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,EAAE,CAAM;IACvD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAM;IACjE,SAAS,CAAC,QAAQ,UAAS;IAC3B,kHAAkH;IAClH,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC/C,sDAAsD;IACtD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,SAAS,aACa,OAAO,EAAE,mBAAmB,EAC/C,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM;WAiBP,KAAK,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC;IAS5E;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAQ1E,6GAA6G;IACvG,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA6BjE,qHAAqH;IACrH,SAAS,CAAC,kBAAkB,CACzB,IAAI,EAAE,qBAAqB,EAC3B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAChC,iBAAiB;IAapB,wGAAwG;IAClG,MAAM,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAiC5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CActG"}