@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/flow/TraceTrial.tsx

@@ -0,0 +1,419 @@
+// A recording, uploaded, on its way into the catalog.
+//
+// The generator has run over a copy of the workspace with the recording in
+// place, and this is what it said: the flows the recording showed, what it
+// raised on them and what it added, and the names it could not place. The
+// reader maps those names, keeps the recording or does not, and watches the
+// real run when they keep it. The panel is the same on the flow page and in
+// settings, because the questions are.
+
+import { useEffect, useMemo, useState } from "react";
+import { ChevronDown, CircleAlert, LoaderCircle, Play, X } from "lucide-react";
+import { Link } from "react-router";
+import { catalog } from "../data";
+import { useToastStore } from "../app/toast";
+import { plural } from "../lib/format";
+import {
+  applyTraceTrial,
+  cancelGeneration,
+  disposeTraceTrial,
+  subscribeToRun,
+} from "../lib/local-api";
+import type { RunEvent, TraceTrial } from "../lib/local-api";
+import { paths } from "../routes";
+
+type Mapping = Record<string, string>;
+
+/**
+ * The events of a run, as they arrive. The server keeps every run's events
+ * and replays them to a late subscriber, so a run picked back up after a
+ * reload reads the same as one watched from the start. `ended` says the
+ * stream closed: with a `process-finished` in it the run is over, without
+ * one the server no longer knows the run.
+ */
+function useRunEvents(runId: string | null): { events: RunEvent[]; ended: boolean } {
+  const [events, setEvents] = useState<RunEvent[]>([]);
+  const [ended, setEnded] = useState(false);
+  useEffect(() => {
+    setEvents([]);
+    setEnded(false);
+    if (!runId) return;
+    return subscribeToRun(
+      runId,
+      (event) => setEvents((current) => [...current, event]),
+      () => setEnded(true),
+    );
+  }, [runId]);
+  return { events, ended };
+}
+
+function Lost({ onClose }: { onClose: () => void }) {
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex items-start gap-2 text-ink">
+        <CircleAlert size={16} className="mt-0.5 shrink-0 text-muted" />
+        <div>The server no longer knows this run - it was restarted, or the run was cancelled. Nothing more can be said about it here.</div>
+      </div>
+      <div className="flex justify-end">
+        <button type="button" className="tbtn" onClick={onClose}>Close</button>
+      </div>
+    </div>
+  );
+}
+
+function Progress({ events, label }: { events: RunEvent[]; label: string }) {
+  const pipeline = events.find((e) => e.type === "pipeline-ready");
+  const steps = events.filter((e) => e.type === "step-finished");
+  const active = events
+    .slice()
+    .reverse()
+    .find((e): e is Extract<RunEvent, { type: "step-started" }> => e.type === "step-started");
+  const total = pipeline?.type === "pipeline-ready" ? pipeline.stepCount : 0;
+  const percent = total ? Math.round((steps.length / total) * 100) : 0;
+  return (
+    <div>
+      <div className="mono flex items-center gap-2 text-muted">
+        <LoaderCircle size={14} className="animate-spin text-accent" />
+        {active ? `${active.phase} · ${active.plugin}` : label}
+        <span className="ml-auto">{steps.length} / {total || "?"}</span>
+      </div>
+      <div className="mt-2 h-1.5 overflow-hidden rounded-full bg-surface">
+        <div className="h-full bg-accent transition-[width]" style={{ width: `${percent}%` }} />
+      </div>
+    </div>
+  );
+}
+
+function Logs({ events }: { events: RunEvent[] }) {
+  const logs = events.filter((e) => e.type === "log");
+  if (!logs.length) return null;
+  return (
+    <details className="mt-3">
+      <summary className="cursor-pointer text-muted">Generator log · {logs.length} lines</summary>
+      <pre className="mono mt-2 max-h-48 overflow-auto whitespace-pre-wrap rounded-control bg-surface p-3 text-muted">
+        {logs.map((e) => (e.type === "log" ? e.message : "")).join("\n")}
+      </pre>
+    </details>
+  );
+}
+
+/**
+ * A name the verifier could not place, and the catalog id it should be.
+ * The list of ids is offered rather than enforced: the verifier says when
+ * the id names nothing, on the next run.
+ */
+type MappingKind = "service" | "event" | "route";
+
+const PLACEHOLDER: Record<MappingKind, string> = {
+  service: "context.service",
+  event: "context.service.aggregate.Event",
+  route: "operation name, as the interface declares it",
+};
+
+function MappingRow({
+  kind,
+  name,
+  value,
+  onChange,
+}: {
+  kind: MappingKind;
+  name: string;
+  value: string;
+  onChange: (next: string) => void;
+}) {
+  const listId = `trace-${kind}-ids`;
+  return (
+    <div className="grid items-center gap-2 sm:grid-cols-[1fr_auto_1fr]">
+      <span className="mono truncate text-ink" title={name}>{name}</span>
+      <span className="mono text-faint">{kind === "route" ? "answers on operation" : `is ${kind}`}</span>
+      <input
+        className="mono w-full rounded-control border border-line bg-canvas px-2.5 py-1.5 text-ink"
+        list={listId}
+        value={value}
+        placeholder={PLACEHOLDER[kind]}
+        onChange={(e) => onChange(e.target.value)}
+        aria-label={`Catalog ${kind} for ${name}`}
+      />
+    </div>
+  );
+}
+
+function IdLists() {
+  const services = useMemo(
+    () => catalog.contexts.flatMap((c) => c.services.map((s) => s.id)),
+    [],
+  );
+  const events = useMemo(
+    () =>
+      catalog.contexts.flatMap((c) =>
+        c.services.flatMap((s) => s.aggregates.flatMap((a) => a.events.map((e) => e.id))),
+      ),
+    [],
+  );
+  const operations = useMemo(
+    () =>
+      [...new Set(
+        catalog.contexts.flatMap((c) =>
+          c.services.flatMap((s) => s.provides.flatMap((p) => p.methods.map((m) => m.name))),
+        ),
+      )].sort(),
+    [],
+  );
+  return (
+    <>
+      <datalist id="trace-service-ids">{services.map((id) => <option key={id} value={id} />)}</datalist>
+      <datalist id="trace-event-ids">{events.map((id) => <option key={id} value={id} />)}</datalist>
+      <datalist id="trace-route-ids">{operations.map((name) => <option key={name} value={name} />)}</datalist>
+    </>
+  );
+}
+
+function FlowRow({ flow }: { flow: TraceTrial["flows"][number] }) {
+  return (
+    <div className="grid gap-x-3 gap-y-1 px-3 py-2 sm:grid-cols-[1fr_auto]">
+      <div className="min-w-0">
+        <Link to={paths.flow(flow.slug)} className="truncate font-medium text-ink hover:underline" title={flow.id}>
+          {flow.name}
+        </Link>
+        <div className="mono mt-0.5 flex flex-wrap gap-x-2 text-muted">
+          <span>{flow.kind === "observed" ? "no flow in the catalog opens this way" : `${flow.verified} of ${flow.steps} steps verified`}</span>
+          {flow.added ? <span>+{flow.added} {plural(flow.added, "hop")} the code does not declare</span> : null}
+        </div>
+      </div>
+      <div className="flex flex-wrap items-center gap-1 sm:justify-end">
+        {flow.inRecording ? (
+          <span className="chip status-verified" title="Traces in this recording that showed the flow">
+            {flow.traces} {plural(flow.traces, "trace")} · {flow.shown} {plural(flow.shown, "step")} shown
+          </span>
+        ) : (
+          <span className="chip" title="Written from recordings the project already had">from earlier recordings</span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * The panel. `runId` is the trial run; when the recording is kept and the
+ * reader asked for it, the write run takes its place until it finishes.
+ */
+export function TraceTrialPanel({
+  runId,
+  initialWriteRunId = null,
+  onWriteStarted,
+  onDone,
+}: {
+  runId: string;
+  /** The write run already started by keeping this recording, when the page comes back to it. */
+  initialWriteRunId?: string | null;
+  /** Keeping the recording started a write run: the page remembers it for a reload. */
+  onWriteStarted?: (writeRunId: string) => void;
+  /** The trial is over: kept and regenerated, kept, or discarded. */
+  onDone: (outcome: "kept" | "discarded") => void;
+}) {
+  const say = useToastStore((s) => s.say);
+  const { events: trialEvents, ended: trialEnded } = useRunEvents(runId);
+  const [writeRunId, setWriteRunId] = useState<string | null>(initialWriteRunId);
+  const { events: writeEvents, ended: writeEnded } = useRunEvents(writeRunId);
+  const [services, setServices] = useState<Mapping>({});
+  const [events, setEvents] = useState<Mapping>({});
+  const [routes, setRoutes] = useState<Mapping>({});
+  const [busy, setBusy] = useState(false);
+  const [kept, setKept] = useState<{ recording: string; manifestChanged: boolean } | null>(null);
+
+  const trial = trialEvents.find(
+    (e): e is Extract<RunEvent, { type: "trace-trial-ready" }> => e.type === "trace-trial-ready",
+  );
+  const trialFinished = trialEvents.find(
+    (e): e is Extract<RunEvent, { type: "process-finished" }> => e.type === "process-finished",
+  );
+  const writeFinished = writeEvents.find(
+    (e): e is Extract<RunEvent, { type: "process-finished" }> => e.type === "process-finished",
+  );
+
+  const unplaced = useMemo(() => {
+    const seen = new Set<string>();
+    return (trial?.warnings ?? []).filter((w) => {
+      if ((w.kind !== "service" && w.kind !== "event" && w.kind !== "route") || !w.name) return false;
+      const key = `${w.kind}:${w.name}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }, [trial]);
+  const others = (trial?.warnings ?? []).filter((w) => w.kind !== "service" && w.kind !== "event" && w.kind !== "route");
+  const shown = (trial?.flows ?? []).filter((f) => f.inRecording);
+  const rest = (trial?.flows ?? []).filter((f) => !f.inRecording);
+
+  async function keep(generate: boolean) {
+    setBusy(true);
+    try {
+      const clean = (m: Mapping) => Object.fromEntries(Object.entries(m).filter(([, v]) => v.trim()).map(([k, v]) => [k, v.trim()]));
+      const result = await applyTraceTrial(runId, { generate, services: clean(services), events: clean(events), routes: clean(routes) });
+      setKept({ recording: result.recording, manifestChanged: result.manifestChanged });
+      if (result.run) {
+        onWriteStarted?.(result.run.runId);
+        setWriteRunId(result.run.runId);
+      } else {
+        say(`${result.recording} kept`);
+        onDone("kept");
+      }
+    } catch (cause) {
+      say(cause instanceof Error ? cause.message : String(cause));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function discard() {
+    setBusy(true);
+    try {
+      await disposeTraceTrial(runId);
+    } catch {
+      // Already gone is discarded too.
+    } finally {
+      setBusy(false);
+      onDone("discarded");
+    }
+  }
+
+  // The write run: the recording is on disk, the catalog is being written.
+  if (writeRunId) {
+    if (writeEnded && !writeFinished) return <Lost onClose={() => onDone("kept")} />;
+    return (
+      <div className="flex flex-col gap-3">
+        {writeFinished ? (
+          <div className="flex items-start gap-2">
+            {writeFinished.status === "ok" ? null : <CircleAlert size={16} className="mt-0.5 shrink-0 text-muted" />}
+            <div>
+              <div className="font-medium text-ink">
+                {writeFinished.status === "ok" ? "Recording kept and documentation regenerated" : `Regeneration ${writeFinished.status}`}
+              </div>
+              <div className="mono mt-0.5 text-muted">{kept?.recording ?? trial?.recording}</div>
+            </div>
+          </div>
+        ) : (
+          <Progress events={writeEvents} label="regenerating with the recording in place…" />
+        )}
+        <Logs events={writeEvents} />
+        <div className="flex justify-end gap-2">
+          {writeFinished ? (
+            <button type="button" className="product-primary" onClick={() => onDone("kept")}>Done</button>
+          ) : (
+            <button type="button" className="tbtn" onClick={() => void cancelGeneration(writeRunId)}>Cancel</button>
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  if (!trialFinished) {
+    if (trialEnded) return <Lost onClose={() => onDone("discarded")} />;
+    return (
+      <div className="flex flex-col gap-3">
+        <Progress events={trialEvents} label="reading the recording against the catalog…" />
+        <Logs events={trialEvents} />
+        <div className="flex justify-end">
+          <button type="button" className="tbtn" onClick={() => void cancelGeneration(runId)}>Cancel</button>
+        </div>
+      </div>
+    );
+  }
+
+  if (!trial) {
+    return (
+      <div className="flex flex-col gap-3">
+        <div className="flex items-start gap-2 text-ink">
+          <CircleAlert size={16} className="mt-0.5 shrink-0 text-muted" />
+          <div>The generator did not finish with the recording in place ({trialFinished.status}). Nothing was written.</div>
+        </div>
+        <Logs events={trialEvents} />
+        <div className="flex justify-end">
+          <button type="button" className="tbtn" onClick={() => void discard()} disabled={busy}>Close</button>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col gap-4">
+      <IdLists />
+      <div>
+        <div className="mono text-muted">
+          {trial.spans} {plural(trial.spans, "span")} · lands at <span className="text-ink">{trial.recording}</span>
+          {trial.stepChange === "added" ? " · adds a verify step to portolan.json" : trial.stepChange === "widened" ? " · points the project's verify step at the recordings directory" : ""}
+        </div>
+      </div>
+
+      <section>
+        <div className="label mb-1.5">flows this recording showed · {shown.length}</div>
+        {shown.length ? (
+          <div className="divide-y divide-line rounded-control border border-line">
+            {shown.map((flow) => <FlowRow key={flow.id} flow={flow} />)}
+          </div>
+        ) : (
+          <div className="rounded-control border border-line bg-surface px-3 py-3 text-muted">
+            No trace in the recording opened a flow of this project. A trace opens a flow on the operation it calls in on or the event that arrives; a service the catalog does not know is reported below.
+          </div>
+        )}
+        {rest.length ? (
+          <details className="mt-2 group">
+            <summary className="flex cursor-pointer items-center gap-1 text-muted">
+              <ChevronDown size={14} className="transition-transform group-open:rotate-180" />
+              {rest.length} {plural(rest.length, "flow")} written from recordings the project already had
+            </summary>
+            <div className="mt-2 divide-y divide-line rounded-control border border-line">
+              {rest.map((flow) => <FlowRow key={flow.id} flow={flow} />)}
+            </div>
+          </details>
+        ) : null}
+      </section>
+
+      {unplaced.length ? (
+        <section>
+          <div className="label mb-1.5">names the verifier could not place · {unplaced.length}</div>
+          <p className="mb-2 text-muted">
+            Say which catalog entry each one is and the mapping is kept in the verify step for every run after this one. Leave one empty to keep the spans it names out; a route left empty opens a flow of its own, written down as it was seen.
+          </p>
+          <div className="flex flex-col gap-2">
+            {unplaced.map((w) =>
+              w.kind === "service" ? (
+                <MappingRow key={`s:${w.name}`} kind="service" name={w.name!} value={services[w.name!] ?? trial.mappings.services[w.name!] ?? ""} onChange={(v) => setServices((m) => ({ ...m, [w.name!]: v }))} />
+              ) : w.kind === "event" ? (
+                <MappingRow key={`e:${w.name}`} kind="event" name={w.name!} value={events[w.name!] ?? trial.mappings.events[w.name!] ?? ""} onChange={(v) => setEvents((m) => ({ ...m, [w.name!]: v }))} />
+              ) : (
+                <MappingRow key={`r:${w.name}`} kind="route" name={w.name!} value={routes[w.name!] ?? trial.mappings.routes?.[w.name!] ?? ""} onChange={(v) => setRoutes((m) => ({ ...m, [w.name!]: v }))} />
+              ),
+            )}
+          </div>
+        </section>
+      ) : null}
+
+      {others.length ? (
+        <details className="group">
+          <summary className="flex cursor-pointer items-center gap-1 text-muted">
+            <ChevronDown size={14} className="transition-transform group-open:rotate-180" />
+            {others.length} {plural(others.length, "other warning")}
+          </summary>
+          <ul className="mt-2 flex flex-col gap-1">
+            {others.map((w, i) => <li key={i} className="mono text-muted">{w.message}</li>)}
+          </ul>
+        </details>
+      ) : null}
+
+      <Logs events={trialEvents} />
+
+      <div className="flex flex-wrap justify-end gap-2">
+        <button type="button" className="tbtn" onClick={() => void discard()} disabled={busy}>
+          <X size={14} /> Discard
+        </button>
+        <button type="button" className="tbtn" onClick={() => void keep(false)} disabled={busy} title="Write the recording beside the project without regenerating now">
+          Keep only
+        </button>
+        <button type="button" className="product-primary" onClick={() => void keep(true)} disabled={busy}>
+          {busy ? <LoaderCircle size={14} className="animate-spin" /> : <Play size={14} />} Keep and regenerate
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/flow/evidence.test.ts

@@ -0,0 +1,16 @@
+import { expect, it } from "vitest";
+import { buildIndex, type Catalog, type Step } from "../catalog";
+import { stepRelationEvidence } from "./evidence";
+
+const index = buildIndex({ generatedAt: "", commit: "", contexts: [], defs: {}, flows: [], adrs: [] } as Catalog);
+it("gives legacy call, event, RPC and response steps an honest source explanation", () => {
+  for (const kind of ["call", "event", "rpc", "response"] as const) {
+    const step: Step = { type: "step", id: "s1", from: "a", to: "b", kind, status: "declared", line: "handler.go:8" };
+    expect(stepRelationEvidence(index, step)).toEqual([{ kind: "call-site", rule: "source-expression", source: "handler.go:8", symbol: undefined }]);
+  }
+});
+it("keeps unresolved status and deduplicates recorded evidence", () => {
+  const evidence = { kind: "call-site" as const, rule: "source-expression", source: "handler.go:8" };
+  const step: Step = { type: "step", id: "s1", from: "a", to: "b", kind: "call", status: "unresolved", line: evidence.source, evidence: [evidence, evidence] };
+  expect(stepRelationEvidence(index, step).map((item) => item.kind)).toEqual(["call-site", "unresolved"]);
+});

package/src/flow/evidence.ts

@@ -0,0 +1,34 @@
+import type { CatalogIndex, RelationEvidence, Step } from "../catalog";
+import { stepRpcContract } from "./answers";
+
+/** Adapt older fragments to the same explanation without inventing a path. */
+export function stepRelationEvidence(index: CatalogIndex, step: Step): RelationEvidence[] {
+  const items = [...(step.evidence ?? [])];
+  if (step.line && !items.some((item) => item.kind === "call-site" && item.source === step.line)) {
+    items.push({ kind: "call-site", rule: "source-expression", source: step.line, symbol: step.label });
+  }
+  const contract = stepRpcContract(index, step);
+  if (contract) items.push({ kind: "contract", rule: "catalog-contract", source: contract.provided.source, symbol: contract.id });
+  if (step.kind === "event" && step.ref) {
+    const event = index.eventById.get(step.ref);
+    const version = event?.versions.at(-1);
+    if (version) items.push({ kind: "contract", rule: "event-declaration", source: version.source, symbol: step.ref });
+  }
+  if (step.storeAccess?.source) items.push({ kind: "binding", rule: "repository-sql-call", source: step.storeAccess.source, symbol: step.storeAccess.method });
+  if (step.destination?.resolution) {
+    const resolution = step.destination.resolution;
+    items.push({ kind: "resolution", rule: resolution.basis, symbol: `${resolution.provider} ${resolution.route}` });
+  }
+  if (step.continuesAt) items.push({ kind: "resolution", rule: "continuation-entrypoint", symbol: step.continuesAt });
+  if (step.kind === "response" && step.replyTo) items.push({ kind: "resolution", rule: "response-to-request", symbol: step.replyTo });
+  if (step.status === "unresolved" && !items.some((item) => item.kind === "unresolved")) {
+    items.push({ kind: "unresolved", rule: "unresolved-target", symbol: step.ref ?? step.label });
+  }
+  const seen = new Set<string>();
+  return items.filter((item) => {
+    const key = JSON.stringify(item);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}

package/src/flow/examples.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+
+import { exampleRowsFor, formatMs, stepsShownBy } from "./examples";
+
+const example = (traceId: string, ...steps: string[]) => ({
+  id: `t.jsonl#${traceId}`,
+  recording: "examples/auth/telemetry/t.jsonl",
+  traceId,
+  durationMs: 3,
+  steps: steps.map((step, i) => ({ step, durationMs: i + 1, attributes: { "http.route": "/x" } })),
+});
+
+describe("what the recordings said about one step", () => {
+  it("is every trace that showed it, in the flow's order, with what the span said", () => {
+    const flow = { examples: [example("a", "s1", "s2"), example("b", "s2", "s2"), example("c", "s3")] };
+    const rows = exampleRowsFor(flow, { id: "s2" });
+    expect(rows.map((row) => `${row.example.traceId}:${row.shown.durationMs}`)).toEqual(["a:2", "b:1", "b:2"]);
+    expect(exampleRowsFor(flow, { id: "s9" })).toEqual([]);
+    expect(exampleRowsFor({}, { id: "s1" })).toEqual([]);
+  });
+
+  it("names the distinct steps a recording showed, once each, in order", () => {
+    expect(stepsShownBy(example("a", "s2", "s1", "s2"))).toEqual(["s2", "s1"]);
+  });
+
+  it("says milliseconds the way a reader does", () => {
+    expect(formatMs(0.42)).toBe("0.42 ms");
+    expect(formatMs(2.6)).toBe("2.6 ms");
+    expect(formatMs(41.39)).toBe("41 ms");
+    expect(formatMs(1300)).toBe("1.3 s");
+    expect(formatMs(12_000)).toBe("12 s");
+  });
+});

package/src/flow/examples.ts

@@ -0,0 +1,37 @@
+// What the recordings said about one step.
+//
+// A flow carries its examples whole - one per trace, in the order the trace
+// ran - and a step's panel wants the other cut: every trace that showed this
+// step, with what the span said. This is that cut, kept apart from the panel
+// so a test can hold it.
+
+import type { ExampleStep, Flow, FlowExample, Step } from "../catalog";
+
+export interface ExampleRow {
+  example: FlowExample;
+  shown: ExampleStep;
+}
+
+/** Every recorded run of the step, in the order the flow keeps its examples. */
+export function exampleRowsFor(
+  flow: Pick<Flow, "examples">,
+  step: Pick<Step, "id">,
+): ExampleRow[] {
+  return (flow.examples ?? []).flatMap((example) =>
+    example.steps
+      .filter((shown) => shown.step === step.id)
+      .map((shown) => ({ example, shown })),
+  );
+}
+
+/** Milliseconds the way a reader says them: 0.4 ms, 12 ms, 1.3 s. */
+export function formatMs(ms: number): string {
+  if (ms >= 1000) return `${(ms / 1000).toFixed(ms >= 10_000 ? 0 : 1)} s`;
+  if (ms >= 10) return `${Math.round(ms)} ms`;
+  return `${ms.toFixed(ms >= 1 ? 1 : 2)} ms`;
+}
+
+/** The distinct steps a recording showed, in the order it showed them. */
+export function stepsShownBy(example: Pick<FlowExample, "steps">): string[] {
+  return [...new Set(example.steps.map((shown) => shown.step))];
+}

package/src/flow/outline.test.ts

@@ -198,6 +198,34 @@ describe("buildOutline", () => {
     expect(outlineSteps(rows).every((r) => !r.offPath)).toBe(true);
   });
 
+  it("gives a counted branch a row even with nothing in it, and says how many went that way", () => {
+    const seen = (id: string) => ({ type: "step" as const, id, from: "client", to: "auth.auth", kind: "rpc" as const, label: id, status: "verified" as const, seen: { traces: 1 } });
+    const parted: Flow = {
+      ...checkout,
+      steps: [
+        seen("s1"),
+        {
+          type: "alt",
+          id: "seen-alt1",
+          branches: [
+            { title: "getUser", steps: [seen("seen1")], seen: { traces: 1 } },
+            { title: "otherwise", steps: [], seen: { traces: 2 } },
+          ],
+        },
+        {
+          type: "alt",
+          id: "alt2",
+          branches: [
+            { title: "blocked", steps: [seen("s9")] },
+            { title: "otherwise", steps: [] },
+          ],
+        },
+      ],
+    };
+    const titles = frames(buildOutline(parted, NO_FILTER)).map((f) => `${f.keyword} ${f.title}`);
+    expect(titles).toEqual(["alt getUser · 1 recording", "else otherwise · 2 recordings", "alt blocked"]);
+  });
+
   it("emits nothing but steps for a flow with no frames", () => {
     const flat = catalog.flows.find(
       (f) =>

package/src/flow/outline.ts

@@ -125,13 +125,18 @@ export function buildOutline(
           let opened = false;
           bodies.forEach((body, i) => {
             const branch = node.branches[i];
-            if (body.length === 0 || !branch) return;
+            // A declared branch with nothing in it is the code's way of
+            // saying "or not", and needs no row. A counted one - the
+            // recordings that went no further - is a fact worth a row.
+            if (!branch || (body.length === 0 && !branch.seen)) return;
             rows.push({
               type: "frame",
               key: `${node.id}:${i}`,
               depth,
               keyword: opened ? "else" : "alt",
-              title: branch.title,
+              title: branch.seen
+                ? `${branch.title} · ${branch.seen.traces} ${branch.seen.traces === 1 ? "recording" : "recordings"}`
+                : branch.title,
               terminal: branch.terminal,
               offPath: false,
             });

package/src/flow/trace-trial-resume.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+
+import { forgetTraceTrial, recallTraceTrial, rememberTraceTrial } from "./trace-trial-resume";
+
+function fakeStorage() {
+  const map = new Map<string, string>();
+  return {
+    getItem: (key: string) => map.get(key) ?? null,
+    setItem: (key: string, value: string) => { map.set(key, value); },
+    removeItem: (key: string) => { map.delete(key); },
+  };
+}
+
+describe("a recording's trial, remembered across a reload", () => {
+  it("is picked up by the page that was watching it, and by no other", () => {
+    const storage = fakeStorage();
+    rememberTraceTrial(storage, "auth-login", { runId: "r1", writeRunId: null });
+    expect(recallTraceTrial(storage, "auth-login")).toEqual({ runId: "r1", writeRunId: null });
+    expect(recallTraceTrial(storage, "settings")).toBeNull();
+
+    rememberTraceTrial(storage, "auth-login", { runId: "r1", writeRunId: "w1" });
+    expect(recallTraceTrial(storage, "auth-login")).toEqual({ runId: "r1", writeRunId: "w1" });
+
+    forgetTraceTrial(storage);
+    expect(recallTraceTrial(storage, "auth-login")).toBeNull();
+  });
+
+  it("ignores what it cannot read, and survives having nowhere to write", () => {
+    const storage = fakeStorage();
+    storage.setItem("portolan.trace-trial.v1", "not json");
+    expect(recallTraceTrial(storage, "x")).toBeNull();
+    storage.setItem("portolan.trace-trial.v1", JSON.stringify({ scope: "x", runId: 3 }));
+    expect(recallTraceTrial(storage, "x")).toBeNull();
+
+    expect(() => rememberTraceTrial(null, "x", { runId: "r", writeRunId: null })).not.toThrow();
+    expect(recallTraceTrial(null, "x")).toBeNull();
+    const broken = { getItem: () => { throw new Error("no"); }, setItem: () => { throw new Error("no"); }, removeItem: () => { throw new Error("no"); } };
+    expect(() => rememberTraceTrial(broken, "x", { runId: "r", writeRunId: null })).not.toThrow();
+    expect(recallTraceTrial(broken, "x")).toBeNull();
+    expect(() => forgetTraceTrial(broken)).not.toThrow();
+  });
+});