effect-inspect 0.2.0 → 0.3.0

package/dist/cli/QueryCommands.js

@@ -181,6 +181,12 @@ COLLECTOR ADDRESS (live only)
   or nothing listens, the result is CollectorUnavailable (exit 8).`;
 const context = `
 CONTEXT FIELDS (every successful per-session response)
+  Top-level siblings of result, never inside it (.completeness, not
+  .result.completeness). result's own fields are listed above (RESULT FIELDS /
+  SPAN ITEM FIELDS); root \`effect-inspect --help\` has the JSON SHAPE overview.
+  notices        summary only, top level: read it first. { code, message } facts easy
+                 to miss (open spans, eviction, sampling gaps); run \`summary\` before
+                 drilling down with other commands.
   query          The request as applied, defaults filled in. Check it to confirm
                  which filters were used.
   source         kind "live"|"file", file (path or null), sessionId (exact), program,
@@ -194,6 +200,15 @@ CONTEXT FIELDS (every successful per-session response)
                  microsecond resolution. Wall clock = startedAtEpochMillis + ms. Values
                  can be negative (work that began before the client). observedFromMs /
                  observedUntilMs: earliest / latest retained timestamp, null when none.
+  termination    state "active" (still connected at snapshot time; open spans may still
+                 end), "ended" (the collector recorded a disconnect) or "unknown" (no
+                 end time on record). lastObservedMs (= observedUntilMs), endedAtMs
+                 (the disconnect in session ms, from the collector's wall clock, so
+                 approximate; null unless ended), unobservedTailMs (endedAtMs -
+                 lastObservedMs: time before the disconnect with nothing retained).
+                 The protocol has no end-of-session message: a crash, a kill, a clean
+                 exit and a dropped connection look the same, so open spans at the end
+                 do not by themselves establish a crash.
   completeness   status: "noLossRecorded" (collector counters known, all loss/gap
                  counters 0 - still not proof nothing is missing), "lossRecorded" (some
                  counter > 0: evidence is partial), or "unknown" (source never kept
@@ -353,7 +368,8 @@ const summaryCommand = Command.make('summary', {
     top: Flag.Int('top').pipe(Flag.optional, Flag.withDescription(`Items per ranked list, 1-${Query.limits.top.max} (default ${Query.limits.top.default}).`)),
     json,
 }, (flags) => Effect.flatMap(answer('summary', flags, given({ top: flags.top })), (response) => emit(response, flags.json))).pipe(Command.withShortDescription('Step 1: counts, failures, longest spans and completeness of one run'), Command.withDescription(text(`
-Overview of one session: span counts by status, failures, the longest spans, the spans
+Overview of one session: notices, span counts by status, failures, unfinished spans
+and where they were last recorded, the longest completed spans, the spans
 with the most time outside recorded children, still-open spans, per-name totals, log
 counts by level and memory samples, plus how complete the evidence is. Start every
 investigation here, then drill down with \`spans\`, \`span\` and \`logs\`.
@@ -362,9 +378,12 @@ ${sourceRules}
 RESULT (abbreviated; lists hold at most --top items)
   { "ok": true, "apiVersion": 1, "op": "summary",
     "query": { "op": "summary", "sessionId": "failing-run-001", "top": 5 },
+    "notices": [],
     "source": { "kind": "live", "sessionId": "failing-run-001", "active": false, ... },
     "time": { "unit": "ms", "reference": "sessionStart",
               "observedFromMs": -1.348, "observedUntilMs": 240.867 },
+    "termination": { "state": "ended", "lastObservedMs": 240.867, "endedAtMs": 243,
+                     "unobservedTailMs": 2.133 },
     "completeness": { "status": "noLossRecorded", "openSpans": 0, ... },
     "conflict": { "count": 0, "detection": "enforced" },
     "result": {
@@ -374,6 +393,7 @@ RESULT (abbreviated; lists hold at most --top items)
       "memory": { "samples": 2, "peakHeapUsedBytes": 7158493, "peakRssBytes": 61489152,
                   "lastHeapUsedBytes": 7158493 },
       "failures": { "total": 4, "items": [ SPAN ITEM, ... ] },
+      "unfinished": { "open": 0, "innermost": { "total": 0, "items": [] } },
       "longest": [ SPAN ITEM, ... ],
       "largestOutsideChildren": [ SPAN ITEM, ... ],
       "longestOpen": [ SPAN ITEM, ... ],
@@ -382,17 +402,41 @@ RESULT (abbreviated; lists hold at most --top items)
         "maxDurationMs": 241.993, "totalOutsideChildrenMs": 0.658 }, ... ] } } }
 
 RESULT FIELDS
+  notices          Top level, before result: { code, message } facts easy to miss.
+                   openSpans (spans without a recorded end, the termination state
+                   and the last recorded position), rankingsCompletedOnly (longest and
+                   largestOutsideChildren skip open spans), collectorEvicted (oldest
+                   messages evicted at capacity: data before observedFromMs is
+                   missing), memorySamplingGap (the largest gap between memory
+                   samples exceeds 10x the median). Messages state facts;
+                   explanations are possibilities.
   spans            Counts by status. failures lists error and defect spans (not
                    interruptions), earliest start first; failures.total counts all.
-  longest          Completed spans, largest durationMs first.
-  largestOutsideChildren  Completed spans, largest outsideChildrenMs first.
+  unfinished       open: spans without a recorded end. innermost: open spans with no
+                   open child - the last recorded position on each open chain, not a
+                   cause - largest elapsedLowerBoundMs first. Each is a SPAN ITEM plus
+                   openAncestors: { items: [ { spanId, name, nameTruncated, status,
+                   startMs, durationMs, elapsedLowerBoundMs } ], truncated }:
+                   contiguous open ancestors, root-most first, at most 32 nearest;
+                   truncated marks more above. durationMs is null (no end);
+                   elapsedLowerBoundMs is observedUntilMs - startMs.
+  longest          Completed spans only, largest durationMs first.
+  largestOutsideChildren  Completed spans only, largest outsideChildrenMs first.
   longestOpen      Open spans, largest elapsedLowerBoundMs first.
   names            Groups by full span name, largest totalDurationMs first. Sums cover
                    completed spans; nested and concurrent spans overlap, so totals can
                    exceed the run's wall time. failed counts every failure incl.
                    interruptions.
-  logs.byLevel     Only levels that occur. memory: { samples, peakHeapUsedBytes,
-                   peakRssBytes, lastHeapUsedBytes } or null without samples.
+  logs.byLevel     Only levels that occur.
+  memory           Process-wide samples (all work in the process), or null without
+                   samples: { samples, peakHeapUsedBytes, peakHeapAtMs, peakRssBytes,
+                   lastHeapUsedBytes, firstSampleMs, lastSampleMs, medianIntervalMs,
+                   maxGapMs, maxGapFromMs, maxGapToMs, spansActiveAtPeak }. Periodic
+                   samples miss peaks between them; maxGapMs is the longest stretch
+                   with no sample. spansActiveAtPeak: { total, items: [ { spanId,
+                   name, nameTruncated, status, startMs, durationMs } ] }, the
+                   innermost spans active at peakHeapAtMs - active at that time only,
+                   not shown to be what the heap in use belongs to.
 ${spanItem}
 ${context}
 ${timing}
@@ -452,9 +496,12 @@ FILTERS (all combine with AND)
 
 ORDER (--sort)
   start            startMs ascending (default).
-  duration         durationMs descending; open spans after completed ones, by
-                   elapsedLowerBoundMs descending.
-  outsideChildren  outsideChildrenMs descending; open spans last, as above.
+  duration         durationMs descending. Open spans are interleaved by
+                   elapsedLowerBoundMs: their true duration is at least that.
+  outsideChildren  outsideChildrenMs descending. Open spans are interleaved by the
+                   time so far no recorded child covered (open children count as
+                   covering up to observedUntilMs): a lower bound, not shown in the
+                   item (their outsideChildrenMs is null).
   Ties: startMs, then spanId.
 ${pagingRules(Query.limits.spans.max, Query.limits.spans.default, 'as --sort')}
 
@@ -462,7 +509,8 @@ RESULT (abbreviated)
   { "ok": true, "apiVersion": 1, "op": "spans",
     "query": { "op": "spans", "sessionId": "failing-run-001", "status": "failed",
                "sort": "start", "limit": 20, "offset": 0 },
-    "source": { ... }, "time": { ... }, "completeness": { ... }, "conflict": { ... },
+    "source": { ... }, "time": { ... }, "termination": { ... },
+    "completeness": { ... }, "conflict": { ... },
     "window": null,
     "result": { "total": 5, "offset": 0, "limit": 20, "nextOffset": null, "items": [
       { "spanId": "0a40c31fbf88b7db", "traceId": "9d502fd678d8f15c0328b182dc1e3509",
@@ -486,7 +534,7 @@ ${exitTable(sessionErrors)}
     },
     {
         command: 'effect-inspect spans --session failing-run-001 --sort outsideChildren --limit 5 --json',
-        description: 'Five spans ranked by elapsed time outside recorded children (completed first; open spans follow by elapsedLowerBoundMs)',
+        description: 'Five spans ranked by elapsed time outside recorded children (open spans by a lower bound)',
     },
     {
         command: 'effect-inspect spans --session failing-run-001 --from-ms=0 --to-ms 50 --sort duration --json',
@@ -516,7 +564,8 @@ RESULT (abbreviated): a SPAN ITEM plus the fields below
   { "ok": true, "apiVersion": 1, "op": "span",
     "query": { "op": "span", "sessionId": "failing-run-001",
                "spanId": "0a40c31fbf88b7db", "children": 20, "events": 20 },
-    "source": { ... }, "time": { ... }, "completeness": { ... }, "conflict": { ... },
+    "source": { ... }, "time": { ... }, "termination": { ... },
+    "completeness": { ... }, "conflict": { ... },
     "result": { "spanId": "0a40c31fbf88b7db", "name": "charge.card", "status": "error",
       ...other SPAN ITEM fields...,
       "attributes": { "entries": [], "omittedKeys": 0 },
@@ -553,6 +602,11 @@ RESULT FIELDS
                  { name, nameTruncated, timeMs, attributes }. Effect logs emitted inside
                  the span are also recorded as its events (as above); use \`logs --span\`
                  for their level and message.
+  processMemory  Process-wide memory samples within the span's interval (open: up to
+                 observedUntilMs): { samples, firstSampleMs, lastSampleMs,
+                 firstHeapUsedBytes, lastHeapUsedBytes, maxHeapUsedBytes }, or null
+                 when no sample falls in range. Includes all concurrent work in the
+                 process; not what this span itself used or kept.
 ${spanItem}
 ${context}
 ${timing}
@@ -609,7 +663,8 @@ RESULT (abbreviated)
   { "ok": true, "apiVersion": 1, "op": "logs",
     "query": { "op": "logs", "sessionId": "failing-run-001",
                "spanId": "0a40c31fbf88b7db", "scope": "subtree", "limit": 50, "offset": 0 },
-    "source": { ... }, "time": { ... }, "completeness": { ... }, "conflict": { ... },
+    "source": { ... }, "time": { ... }, "termination": { ... },
+    "completeness": { ... }, "conflict": { ... },
     "window": null,
     "result": { "total": 1, "offset": 0, "limit": 50, "nextOffset": null, "items": [
       { "timeMs": -0.506, "level": "Info", "message": "charging card **** 4242",

package/dist/cli.js

@@ -110,6 +110,21 @@ OUTPUT AND EXIT CODES (all query commands)
   8 CollectorUnavailable    9 CollectorError          10 OutputError (export)
   Each command's --help explains its errors and what to do next.
 
+JSON SHAPE (success, per-session queries)
+  Top-level keys: ok, apiVersion, op, query, notices (summary only), source, time,
+  termination, completeness, conflict, result (spans and logs add window).
+  Context keys are siblings of result, never inside it: .completeness, not
+  .result.completeness. Most-used paths:
+  .notices[]                  summary: read first; { code, message } facts easy to miss
+  .result.spans.open          summary: span counts by status (also total, ok, error, ...)
+  .result.unfinished          summary: innermost open spans and their open ancestors
+  .result.longest[].durationMs  summary: completed spans only, longest first
+  .result.memory              summary: heap peak, sampling gaps; null without samples
+  .result.items[]             spans and logs: the page (with total, nextOffset)
+  .completeness.status        noLossRecorded | lossRecorded | unknown
+  .termination.state          active | ended | unknown
+  Full field lists: \`<command> --help\` (RESULT FIELDS or SPAN ITEM FIELDS, CONTEXT FIELDS).
+
 EVIDENCE AND TIMING
   Times are milliseconds since the session's clock origin (when its inspect client
   started) and can be negative. durationMs is elapsed wall time; outsideChildrenMs is

package/dist/query/Query.d.ts

@@ -339,10 +339,32 @@ export interface ConflictInfo {
     readonly count: number | null;
     readonly detection: 'enforced' | 'unavailable' | 'unknown';
 }
+/**
+ * How the session ended, as far as the collector knows. The protocol has no
+ * end-of-session message: a crash, a kill, a clean exit and a dropped
+ * connection all look the same here, so open spans at the end do not by
+ * themselves establish a crash. `state`:
+ * - `active`: still connected at snapshot time; open spans may still end.
+ * - `ended`: the collector recorded a disconnect.
+ * - `unknown`: no end time is on record.
+ */
+export interface Termination {
+    readonly state: 'active' | 'ended' | 'unknown';
+    /** Latest retained timestamp (= `time.observedUntilMs`). */
+    readonly lastObservedMs: number | null;
+    /**
+     * When the collector recorded the disconnect, in session ms. Taken from the
+     * collector's wall clock, not the client's, so approximate.
+     */
+    readonly endedAtMs: number | null;
+    /** `endedAtMs - lastObservedMs`: time before the disconnect with nothing retained. */
+    readonly unobservedTailMs: number | null;
+}
 /** Shared context of every successful per-session response. */
 export interface Context {
     readonly source: SourceInfo;
     readonly time: TimeInfo;
+    readonly termination: Termination;
     readonly completeness: Completeness;
     readonly conflict: ConflictInfo;
 }
@@ -410,6 +432,19 @@ export interface SpanRef {
     readonly startMs: number;
     readonly durationMs: number | null;
 }
+/**
+ * Process-wide memory samples within a span's interval (open: up to
+ * `observedUntilMs`). Includes all concurrent work in the process; not what
+ * the span itself used or kept.
+ */
+export interface ProcessMemory {
+    readonly samples: number;
+    readonly firstSampleMs: number;
+    readonly lastSampleMs: number;
+    readonly firstHeapUsedBytes: number;
+    readonly lastHeapUsedBytes: number;
+    readonly maxHeapUsedBytes: number;
+}
 export interface SpanDetail extends SpanItem {
     readonly attributes: BoundedAttributes;
     readonly stack: string | null;
@@ -447,6 +482,8 @@ export interface SpanDetail extends SpanItem {
             readonly attributes: BoundedAttributes;
         }>;
     };
+    /** `null` when no memory sample falls in the span's interval. */
+    readonly processMemory: ProcessMemory | null;
 }
 export interface LogItem {
     readonly timeMs: number;
@@ -483,6 +520,23 @@ export interface NameGroup {
     readonly maxDurationMs: number | null;
     readonly totalOutsideChildrenMs: number;
 }
+/** An open span with no open child: the last recorded position on its open chain. */
+export interface UnfinishedSpan extends SpanItem {
+    /** Contiguous open ancestors, root-most first, ending at the direct parent. */
+    readonly openAncestors: {
+        /** `elapsedLowerBoundMs`: `observedUntilMs - startMs`, as on open span items. */
+        readonly items: ReadonlyArray<SpanRef & {
+            readonly elapsedLowerBoundMs: number;
+        }>;
+        /** More open ancestors exist above the first item. */
+        readonly truncated: boolean;
+    };
+}
+/** A plain factual statement about the evidence; possible explanations are phrased as such. */
+export interface Notice {
+    readonly code: 'openSpans' | 'rankingsCompletedOnly' | 'collectorEvicted' | 'memorySamplingGap';
+    readonly message: string;
+}
 export interface Summary {
     readonly spans: {
         readonly total: number;
@@ -497,17 +551,51 @@ export interface Summary {
         readonly total: number;
         readonly byLevel: Partial<Record<Protocol.LogLevel, number>>;
     };
+    /**
+     * Process-wide memory samples (all work in the process, not per span).
+     * Samples are periodic, so peaks between samples are not seen.
+     */
     readonly memory: {
         readonly samples: number;
         readonly peakHeapUsedBytes: number;
+        /** Time of the first sample with `peakHeapUsedBytes`. */
+        readonly peakHeapAtMs: number;
         readonly peakRssBytes: number;
         readonly lastHeapUsedBytes: number;
+        readonly firstSampleMs: number;
+        readonly lastSampleMs: number;
+        /** Median time between consecutive samples; `null` with one sample. */
+        readonly medianIntervalMs: number | null;
+        /** Largest time between consecutive samples, from `maxGapFromMs` to `maxGapToMs`; `null` with one sample. */
+        readonly maxGapMs: number | null;
+        readonly maxGapFromMs: number | null;
+        readonly maxGapToMs: number | null;
+        /**
+         * Innermost spans active at `peakHeapAtMs` (none of their children active
+         * then), earliest start first. Active at that time only: they are not
+         * shown to be the source of the heap in use.
+         */
+        readonly spansActiveAtPeak: {
+            readonly total: number;
+            readonly items: ReadonlyArray<SpanRef>;
+        };
     } | null;
     /** `error`/`defect` spans (not interruptions), earliest start first. */
     readonly failures: {
         readonly total: number;
         readonly items: ReadonlyArray<SpanItem>;
     };
+    /**
+     * Spans with no recorded end. `innermost`: open spans without an open child,
+     * largest `elapsedLowerBoundMs` first, each with its open ancestor chain.
+     */
+    readonly unfinished: {
+        readonly open: number;
+        readonly innermost: {
+            readonly total: number;
+            readonly items: ReadonlyArray<UnfinishedSpan>;
+        };
+    };
     /** Completed spans, largest `durationMs` first. */
     readonly longest: ReadonlyArray<SpanItem>;
     /** Completed spans, largest `outsideChildrenMs` first. */
@@ -547,7 +635,9 @@ export type SessionsResponse = Success<'sessions', SessionsResult> & {
         readonly file: string | null;
     };
 };
-export type SummaryResponse = Success<'summary', Summary> & Context;
+export type SummaryResponse = Success<'summary', Summary> & {
+    readonly notices: ReadonlyArray<Notice>;
+} & Context;
 /**
  * How `fromMs`/`toMs` were applied to `spans`, or `null` without either:
  * spans whose `[startMs, endMs]` (open: `[startMs, observedUntilMs]`)

package/dist/query/Query.js

@@ -316,6 +316,8 @@ class Analysis {
     outOfOrder;
     clientDropped;
     items = new Map();
+    /** Open spans: time so far not covered by a recorded child, a lower bound. */
+    openOutside = new Map();
     constructor(source) {
         this.source = source;
         const store = this.store;
@@ -392,6 +394,8 @@ class Analysis {
         }
         const closed = span.end !== undefined;
         const { total, self } = timings(this.store, span, this.now);
+        if (!closed)
+            this.openOutside.set(span.spanId, ms(self));
         const error = span.outcome?._tag === 'Failure'
             ? (() => {
                 const { text, truncated } = cut(span.outcome.error, limits.errorChars);
@@ -443,6 +447,15 @@ class Analysis {
         let detection = 'unknown';
         if (capture !== undefined)
             detection = capture.conflictDetection ? 'enforced' : 'unavailable';
+        const lastObservedMs = this.observedUntil === undefined ? null : ms(this.observedUntil);
+        const endedAtMs = session.endedAtEpochMillis === undefined
+            ? null
+            : ms(session.endedAtEpochMillis - session.clock.wallClockEpochMillis);
+        let state = 'unknown';
+        if (session.active)
+            state = 'active';
+        else if (endedAtMs !== null)
+            state = 'ended';
         return {
             source: {
                 kind: source.kind,
@@ -458,7 +471,13 @@ class Analysis {
                 unit: 'ms',
                 reference: 'sessionStart',
                 observedFromMs: this.observedFrom === undefined ? null : ms(this.observedFrom),
-                observedUntilMs: this.observedUntil === undefined ? null : ms(this.observedUntil),
+                observedUntilMs: lastObservedMs,
+            },
+            termination: {
+                state,
+                lastObservedMs,
+                endedAtMs,
+                unobservedTailMs: endedAtMs === null || lastObservedMs === null ? null : ms(endedAtMs - lastObservedMs),
             },
             completeness: {
                 status,
@@ -482,19 +501,50 @@ const page = (all, offset, limit) => ({
     items: all.slice(offset, offset + limit),
 });
 const byStart = (a, b) => a.startMs - b.startMs || (a.spanId < b.spanId ? -1 : Number(a.spanId > b.spanId));
-/** Completed spans by `measure` descending, then open spans by lower bound; ties by start. */
-const ranked = (measure) => (a, b) => {
-    const aOpen = a.endMs === null;
-    const bOpen = b.endMs === null;
-    if (aOpen !== bOpen)
-        return aOpen ? 1 : -1;
-    const key = aOpen ? 'elapsedLowerBoundMs' : measure;
-    return b[key] - a[key] || byStart(a, b);
+/** `measure` descending, ties by start. */
+const ranked = (measure) => (a, b) => measure(b) - measure(a) || byStart(a, b);
+/**
+ * Open spans interleave with completed ones by a lower bound of the measure:
+ * `elapsedLowerBoundMs` for duration, and for outside-children time the part
+ * of it no recorded child covered so far (open children counted up to now).
+ */
+const sorter = (sort, analysis) => {
+    if (sort === 'start')
+        return byStart;
+    if (sort === 'duration')
+        return ranked((item) => item.durationMs ?? item.elapsedLowerBoundMs);
+    return ranked((item) => item.outsideChildrenMs ?? analysis.openOutside.get(item.spanId));
+};
+/** Nearest `limits.ancestry` ancestors, root-most first; with `openOnly`, only the contiguous open ones. */
+const ancestry = (analysis, span, openOnly) => {
+    const { store } = analysis;
+    const items = [];
+    const seen = new Set([span.spanId]);
+    let parent = span.parentId === undefined ? undefined : store.spans.get(span.parentId);
+    let truncated = false;
+    while (parent !== undefined &&
+        !seen.has(parent.spanId) &&
+        !(openOnly && parent.end !== undefined)) {
+        if (items.length === limits.ancestry) {
+            truncated = true;
+            break;
+        }
+        seen.add(parent.spanId);
+        items.push(ref(analysis, parent));
+        parent = parent.parentId === undefined ? undefined : store.spans.get(parent.parentId);
+    }
+    return { items: items.reverse(), truncated };
 };
-const sorters = {
-    start: byStart,
-    duration: ranked('durationMs'),
-    outsideChildren: ranked('outsideChildrenMs'),
+const openAncestors = (analysis, span) => {
+    const { items, truncated } = ancestry(analysis, span, true);
+    return {
+        items: items.map((item) => ({
+            ...item,
+            elapsedLowerBoundMs: analysis.item(analysis.store.spans.get(item.spanId))
+                .elapsedLowerBoundMs,
+        })),
+        truncated,
+    };
 };
 const summarize = (analysis, top) => {
     const items = [...analysis.store.spans.values()].map((span) => analysis.item(span));
@@ -534,30 +584,31 @@ const summarize = (analysis, top) => {
     for (const log of analysis.store.logs)
         byLevel[log.level] = (byLevel[log.level] ?? 0) + 1;
     const completed = items.filter((item) => item.endMs !== null);
+    const open = items.filter((item) => item.endMs === null).sort(sorter('duration', analysis));
+    const innermost = open.filter((item) => item.openChildCount === 0);
     const failures = items
         .filter((item) => item.status === 'error' || item.status === 'defect')
         .sort(byStart);
     const { store } = analysis;
-    const last = store.memory.at(-1);
     return {
         spans: counts,
         spanEvents: store.stats().events,
         logs: { total: store.logs.length, byLevel },
-        memory: last === undefined
-            ? null
-            : {
-                samples: store.memory.length,
-                peakHeapUsedBytes: store.memoryPeak,
-                peakRssBytes: store.memoryRssPeak,
-                lastHeapUsedBytes: last.heapUsed,
-            },
+        memory: memorySummary(analysis, top),
         failures: { total: failures.length, items: failures.slice(0, top) },
-        longest: completed.toSorted(sorters.duration).slice(0, top),
-        largestOutsideChildren: completed.toSorted(sorters.outsideChildren).slice(0, top),
-        longestOpen: items
-            .filter((item) => item.endMs === null)
-            .sort(sorters.duration)
-            .slice(0, top),
+        unfinished: {
+            open: open.length,
+            innermost: {
+                total: innermost.length,
+                items: innermost.slice(0, top).map((item) => ({
+                    ...item,
+                    openAncestors: openAncestors(analysis, store.spans.get(item.spanId)),
+                })),
+            },
+        },
+        longest: completed.toSorted(sorter('duration', analysis)).slice(0, top),
+        largestOutsideChildren: completed.toSorted(sorter('outsideChildren', analysis)).slice(0, top),
+        longestOpen: open.slice(0, top),
         names: {
             total: groups.size,
             items: [...groups.values()]
@@ -572,6 +623,59 @@ const summarize = (analysis, top) => {
         },
     };
 };
+const memorySummary = (analysis, top) => {
+    const { store } = analysis;
+    const samples = store.memory;
+    const first = samples[0];
+    const last = samples.at(-1);
+    if (first === undefined || last === undefined)
+        return null;
+    const peak = samples.find((sample) => sample.heapUsed === store.memoryPeak);
+    const gaps = samples.slice(1).map((sample, i) => sample.time - samples[i].time);
+    let gapAt = -1;
+    for (let i = 0; i < gaps.length; i++)
+        if (gapAt < 0 || gaps[i] > gaps[gapAt])
+            gapAt = i;
+    const sorted = gaps.toSorted((a, b) => a - b);
+    const mid = sorted.length >> 1;
+    const median = sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+    const active = [...store.spans.values()].filter((span) => span.start <= peak.time && (span.end ?? Number.POSITIVE_INFINITY) >= peak.time);
+    const ids = new Set(active.map((span) => span.spanId));
+    const innermost = active
+        .filter((span) => !span.children.some((id) => ids.has(id)))
+        .map((span) => ref(analysis, span))
+        .sort((a, b) => a.startMs - b.startMs || (a.spanId < b.spanId ? -1 : 1));
+    return {
+        samples: samples.length,
+        peakHeapUsedBytes: store.memoryPeak,
+        peakHeapAtMs: ms(peak.time),
+        peakRssBytes: store.memoryRssPeak,
+        lastHeapUsedBytes: last.heapUsed,
+        firstSampleMs: ms(first.time),
+        lastSampleMs: ms(last.time),
+        medianIntervalMs: gaps.length === 0 ? null : ms(median),
+        maxGapMs: gapAt < 0 ? null : ms(gaps[gapAt]),
+        maxGapFromMs: gapAt < 0 ? null : ms(samples[gapAt].time),
+        maxGapToMs: gapAt < 0 ? null : ms(samples[gapAt + 1].time),
+        spansActiveAtPeak: { total: innermost.length, items: innermost.slice(0, top) },
+    };
+};
+const processMemory = (analysis, span) => {
+    const until = span.end ?? analysis.now;
+    const inRange = analysis.store.memory.filter((sample) => sample.time >= span.start && sample.time <= until);
+    const first = inRange[0];
+    const last = inRange.at(-1);
+    if (first === undefined || last === undefined)
+        return null;
+    return {
+        samples: inRange.length,
+        firstSampleMs: ms(first.time),
+        lastSampleMs: ms(last.time),
+        firstHeapUsedBytes: first.heapUsed,
+        lastHeapUsedBytes: last.heapUsed,
+        maxHeapUsedBytes: Math.max(...inRange.map((sample) => sample.heapUsed)),
+    };
+};
 const ref = (analysis, span) => {
     const item = analysis.item(span);
     return {
@@ -585,19 +689,6 @@ const ref = (analysis, span) => {
 };
 const detail = (analysis, span, childLimit, eventLimit) => {
     const { store } = analysis;
-    const ancestry = [];
-    const seen = new Set([span.spanId]);
-    let parent = span.parentId === undefined ? undefined : store.spans.get(span.parentId);
-    let truncated = false;
-    while (parent !== undefined && !seen.has(parent.spanId)) {
-        if (ancestry.length === limits.ancestry) {
-            truncated = true;
-            break;
-        }
-        seen.add(parent.spanId);
-        ancestry.push(ref(analysis, parent));
-        parent = parent.parentId === undefined ? undefined : store.spans.get(parent.parentId);
-    }
     const external = analysis.externalParents.get(span.spanId);
     let parentInfo = { kind: 'none' };
     if (external !== undefined) {
@@ -622,7 +713,7 @@ const detail = (analysis, span, childLimit, eventLimit) => {
         stack: stack?.text ?? null,
         stackTruncated: stack?.truncated ?? false,
         parent: parentInfo,
-        ancestry: { items: ancestry.reverse(), truncated },
+        ancestry: ancestry(analysis, span, false),
         children: { total: children.length, items: children.slice(0, childLimit) },
         events: {
             total: events.length,
@@ -636,6 +727,7 @@ const detail = (analysis, span, childLimit, eventLimit) => {
                 };
             }),
         },
+        processMemory: processMemory(analysis, span),
     };
 };
 /** Span ids of `root` and every retained descendant. */
@@ -660,6 +752,53 @@ const spanNotFound = (op, spanId, analysis) => failure(op, 'SpanNotFound', 'The
     sessionId: analysis.source.session.sessionId,
     completeness: analysis.context().completeness,
 });
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+/** Facts a reader of `summary` could otherwise miss, most important first. */
+const notices = (context, { unfinished, memory }) => {
+    const out = [];
+    const { termination, completeness, time } = context;
+    if (unfinished.open > 0) {
+        const spans = plural(unfinished.open, 'span');
+        const first = unfinished.innermost.items[0];
+        const outer = first?.openAncestors.items[0];
+        const within = outer === undefined
+            ? ''
+            : `, within "${outer.name}" (spanId ${outer.spanId}), open for at least ${outer.elapsedLowerBoundMs} ms`;
+        const position = first === undefined
+            ? ''
+            : ` Last recorded position: "${first.name}" (spanId ${first.spanId}), open for at least ${first.elapsedLowerBoundMs} ms${within}, innermost of ${plural(unfinished.innermost.total, 'open chain')}; see result.unfinished.`;
+        let message;
+        if (termination.state === 'active') {
+            message = `${spans} had no recorded end at snapshot time and the program is still connected; they may still end.${position}`;
+        }
+        else {
+            const ended = termination.state === 'ended'
+                ? `the collector recorded a disconnect at ${termination.endedAtMs} ms${termination.unobservedTailMs === null ? '' : `, ${termination.unobservedTailMs} ms after the last retained message, with nothing retained in between`}`
+                : 'no session end time is on record';
+            message = `${spans} had no recorded end; ${ended}.${position} The protocol has no end-of-session message, so a crash, a kill, an exit without closing spans and a dropped connection look the same; missing ends alone do not establish which, and an end may also have been sent but lost.`;
+        }
+        out.push({ code: 'openSpans', message });
+        out.push({
+            code: 'rankingsCompletedOnly',
+            message: `result.longest and result.largestOutsideChildren rank completed spans only; the ${spans} without an end are in result.unfinished and result.longestOpen.`,
+        });
+    }
+    const evicted = completeness.collectorDroppedMessages ?? 0;
+    if (evicted > 0) {
+        out.push({
+            code: 'collectorEvicted',
+            message: `The collector evicted the oldest ${plural(evicted, 'message')} of this session at its capacity: data before observedFromMs (${time.observedFromMs} ms) is missing, so earlier spans, logs and memory samples are absent and retained spans may lack their start or parent.`,
+        });
+    }
+    // ponytail: fixed 10x threshold; the sampling interval is not in the protocol.
+    if (memory?.maxGapMs != null && memory.maxGapMs > 10 * memory.medianIntervalMs) {
+        out.push({
+            code: 'memorySamplingGap',
+            message: `Memory samples are ${memory.medianIntervalMs} ms apart at the median, but no sample was retained for ${memory.maxGapMs} ms (from ${memory.maxGapFromMs} ms to ${memory.maxGapToMs} ms); process memory in that interval is unknown. The cause is not recorded. Possible explanations: synchronous work blocked the event loop so the sampling timer could not run, or the client's outbound queue was full and dropped samples (see completeness.clientDroppedMessages).`,
+        });
+    }
+    return out;
+};
 // ---------------------------------------------------------------------------
 // Entry points
 // ---------------------------------------------------------------------------
@@ -716,13 +855,15 @@ const answer = (source, request) => {
     switch (request.op) {
         case 'summary': {
             const top = request.top ?? limits.top.default;
+            const result = summarize(analysis, top);
             return {
                 ok: true,
                 apiVersion,
                 op: 'summary',
                 query: { op, sessionId, top },
+                notices: notices(context, result),
                 ...context,
-                result: summarize(analysis, top),
+                result,
             };
         }
         case 'spans': {
@@ -748,7 +889,7 @@ const answer = (source, request) => {
                     continue;
                 matched.push(item);
             }
-            matched.sort(sorters[sort]);
+            matched.sort(sorter(sort, analysis));
             return {
                 ok: true,
                 apiVersion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-inspect",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "description": "A live inspector for Effect programs",
   "repository": {