@shortlink-org/portolan 0.3.0 → 0.4.0

package/scripts/plugins-fresh.test.mjs

@@ -0,0 +1,64 @@
+import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { newestMtime, pluginsFresh } from "./plugins-fresh.mjs";
+
+const roots = [];
+afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+
+function at(path, seconds) {
+  utimesSync(path, seconds, seconds);
+}
+
+/** A workspace with a built wasm and Java classes, all stamped at `built`, over sources stamped at `source`. */
+function workspace({ source, built }) {
+  const root = mkdtempSync(join(tmpdir(), "portolan-fresh-"));
+  roots.push(root);
+  for (const dir of ["plugins/verify-otel", "plugins/extract-java/src/org", "plugins/extract-java/build/org", "catalog", "plugin"]) mkdirSync(join(root, dir), { recursive: true });
+  const files = {
+    "go.mod": source, "plugins/verify-otel/verify.go": source, "catalog/model.go": source, "plugin/protocol.go": source,
+    "plugins/extract-java/src/org/Main.java": source,
+    "plugins/portolan-go.wasm": built, "plugins/extract-java/build/org/Main.class": built,
+  };
+  for (const [name, stamp] of Object.entries(files)) {
+    writeFileSync(join(root, name), "x");
+    at(join(root, name), stamp);
+  }
+  return root;
+}
+
+describe("whether the built plugins are newer than their sources", () => {
+  it("is yes when every artefact is at least as new as every source", () => {
+    expect(pluginsFresh(workspace({ source: 1000, built: 2000 }))).toBe(true);
+    expect(pluginsFresh(workspace({ source: 2000, built: 2000 }))).toBe(true);
+  });
+
+  it("is no when a Go source, a Java source, or go.mod is newer, or an artefact is missing", () => {
+    const go = workspace({ source: 1000, built: 2000 });
+    at(join(go, "catalog/model.go"), 3000);
+    expect(pluginsFresh(go)).toBe(false);
+
+    const java = workspace({ source: 1000, built: 2000 });
+    at(join(java, "plugins/extract-java/src/org/Main.java"), 3000);
+    expect(pluginsFresh(java)).toBe(false);
+
+    const mod = workspace({ source: 1000, built: 2000 });
+    at(join(mod, "go.mod"), 3000);
+    expect(pluginsFresh(mod)).toBe(false);
+
+    const missing = workspace({ source: 1000, built: 2000 });
+    rmSync(join(missing, "plugins/portolan-go.wasm"));
+    expect(pluginsFresh(missing)).toBe(false);
+  });
+
+  it("leaves a plugin's own build output and test data out of the sources", () => {
+    const root = workspace({ source: 1000, built: 2000 });
+    mkdirSync(join(root, "plugins/extract-rust/target"), { recursive: true });
+    writeFileSync(join(root, "plugins/extract-rust/target/out.go"), "x");
+    at(join(root, "plugins/extract-rust/target/out.go"), 5000);
+    expect(pluginsFresh(root)).toBe(true);
+    expect(newestMtime(join(root, "plugins"), (path) => path.endsWith(".go"))).toBe(1000 * 1000);
+  });
+});

package/scripts/run-builtin.mjs

@@ -27,8 +27,9 @@ if (!plugin?.process) {
 const command = plugin.process.command;
 const args = [...(plugin.process.args ?? [])];
 
-if (command === "cargo" && existsSync(resolve(installRoot, "plugins/extract-rust/target/release/portolan-extract-rust"))) {
-  run(resolve(installRoot, "plugins/extract-rust/target/release/portolan-extract-rust"), []);
+const prebuilt = command === "cargo" ? prebuiltCargoBinary(args) : "";
+if (prebuilt) {
+  run(prebuilt, []);
 } else if (command === "go") {
   buildAndRunGo(args);
 } else {
@@ -49,7 +50,14 @@ if (command === "cargo" && existsSync(resolve(installRoot, "plugins/extract-rust
 // describe/extract calls cheap; rebuilding also prevents a stale sidecar after
 // an npm upgrade with the same workspace cache.
 function buildAndRunGo(argv) {
-  if (argv[0] !== "run" || typeof argv[1] !== "string" || !argv[1] || argv[1].startsWith("-")) {
+  // `go run [build flags] <package> [args]`: the build flags (-mod=mod, -tags)
+  // belong to the build, the package is what is built, the rest is the
+  // sidecar's own command line.
+  const flags = [];
+  let at = 1;
+  while (argv[0] === "run" && typeof argv[at] === "string" && argv[at].startsWith("-")) flags.push(argv[at++]);
+  const pkg = argv[at];
+  if (argv[0] !== "run" || typeof pkg !== "string" || !pkg) {
     console.error(`portolan: built-in ${name} has an unsupported Go command`);
     process.exitCode = 2;
     return;
@@ -57,7 +65,7 @@ function buildAndRunGo(argv) {
   const binDir = resolve(workspace, ".portolan", "bin", "go");
   const executable = resolve(binDir, process.platform === "win32" ? `${name}.exe` : name);
   mkdirSync(binDir, { recursive: true });
-  const built = spawnSync("go", ["build", "-mod=readonly", "-o", executable, argv[1]], {
+  const built = spawnSync("go", ["build", "-mod=mod", ...flags.filter((flag) => flag !== "-mod=mod"), "-o", executable, pkg], {
     cwd: installRoot,
     env: { ...process.env, GOWORK: "off" },
     stdio: "inherit",
@@ -71,12 +79,25 @@ function buildAndRunGo(argv) {
     process.exitCode = built.status ?? 1;
     return;
   }
-  run(executable, argv.slice(2));
+  run(executable, argv.slice(at + 1));
+}
+
+// A Rust plugin already built in release mode under its own crate directory,
+// `plugins/extract-rust/target/release/portolan-extract-rust`, is run as it
+// is; the crate is named after its directory, which is what the manifest
+// path names.
+function prebuiltCargoBinary(argv) {
+  const manifest = argv[argv.indexOf("--manifest-path") + 1];
+  if (!manifest || argv.indexOf("--manifest-path") < 0) return "";
+  const crate = dirname(manifest).split("/").pop();
+  const binary = resolve(installRoot, dirname(manifest), "target", "release", `portolan-${crate}`);
+  return existsSync(binary) ? binary : "";
 }
 
 function resolveArgument(executable, index) {
   if (["node", "python", "python3"].includes(executable)) return index === 0;
   if (executable === "java") return index === 1;
+  if (executable === "dotnet") return index === 0;
   if (executable === "cargo") return index === 3;
   return false;
 }

package/scripts/schema.mjs

@@ -1,8 +1,9 @@
 // Composes the JSON Schema for portolan.json out of what the plugins say about
 // themselves.
 //
-//   node scripts/schema.mjs            write schema/portolan.schema.json
-//   node scripts/schema.mjs --check    fail if the schema on disk is not what
+//   node scripts/schema.mjs            write schema/portolan.schema.json and
+//                                      src/lib/plugin-index.json
+//   node scripts/schema.mjs --check    fail if either file on disk is not what
 //                                      the plugins describe now
 //
 // The manifest tells each plugin the things its source cannot carry - which
@@ -19,8 +20,14 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 
 import { describePlugin } from "./plugin-host.mjs";
+import { RULE_ID, SEVERITIES, SUBJECT_NAMES, SUBJECTS } from "../src/lib/problem-rules-cel.mjs";
+
+// The built-in problem rules, so the schema can say which ids are switches
+// and which must carry a whole rule.
+const BUILTIN_RULES = JSON.parse(readFileSync("rules/builtin.json", "utf8"));
 
 const OUT = "schema/portolan.schema.json";
+const INDEX = "src/lib/plugin-index.json";
 
 const check = process.argv.includes("--check");
 // Bootstrap exception: this command produces the schema that loadManifest
@@ -51,25 +58,65 @@ for (const plugin of manifest.plugins ?? []) {
 }
 
 const composed = `${JSON.stringify(compose(), null, 2)}\n`;
+const index = `${JSON.stringify(pluginIndex(), null, 2)}\n`;
+
+let stale = false;
+for (const [path, contents, directory] of [
+  [OUT, composed, "schema"],
+  [INDEX, index, "src/lib"],
+]) {
+  let current = null;
+  try {
+    current = readFileSync(path, "utf8");
+  } catch {
+    // Absent, which is the same as out of date.
+  }
 
-let current = null;
-try {
-  current = readFileSync(OUT, "utf8");
-} catch {
-  // Absent, which is the same as out of date.
+  if (current === contents) {
+    console.log(`${path}: up to date`);
+  } else if (check) {
+    console.error(
+      `${path} is ${current === null ? "missing" : "out of date"}. Run \`npm run schema\`.`,
+    );
+    stale = true;
+  } else {
+    mkdirSync(directory, { recursive: true });
+    writeFileSync(path, contents);
+    console.log(`${path}: written from ${described.size} plugin${described.size === 1 ? "" : "s"}`);
+  }
 }
+if (stale) process.exit(1);
 
-if (current === composed) {
-  console.log(`${OUT}: up to date`);
-} else if (check) {
-  console.error(
-    `${OUT} is ${current === null ? "missing" : "out of date"}. Run \`npm run schema\`.`,
-  );
-  process.exit(1);
-} else {
-  mkdirSync("schema", { recursive: true });
-  writeFileSync(OUT, composed);
-  console.log(`${OUT}: written from ${described.size} plugin${described.size === 1 ? "" : "s"}`);
+/**
+ * The plugin index: every plugin the package ships, as it describes itself,
+ * with how the manifest runs it. The site's /plugins page and the landing's
+ * list of inputs are rendered from this, so a plugin added to portolan.json
+ * appears there without anyone writing it down twice. Kept under src/ rather
+ * than beside the schema because the staged site copies src/ and nothing else.
+ */
+function pluginIndex() {
+  const out = [];
+  for (const plugin of manifest.plugins ?? []) {
+    const descriptor = described.get(plugin.name);
+    if (!descriptor) continue;
+    out.push({
+      name: plugin.name,
+      plugin: descriptor.name,
+      summary: descriptor.summary,
+      category: descriptor.category,
+      phases: descriptor.phases,
+      ...(descriptor.needs?.length ? { needs: descriptor.needs } : {}),
+      runtime: plugin.wasm ? "wasm" : plugin.host ? "host" : "process",
+      // The toolchain a process plugin asks the build for; the sandboxed
+      // module and the host's own code ask for nothing.
+      ...(plugin.process ? { toolchain: plugin.process.command } : {}),
+      source: plugin.host
+        ? `scripts/host-plugins/${plugin.host}.mjs`
+        : `plugins/${descriptor.name}`,
+      options: descriptor.options ?? {},
+    });
+  }
+  return out;
 }
 
 function compose() {
@@ -123,6 +170,13 @@ function compose() {
         description:
           "CEL policies for reviewed extraction limitations. Expressions are type-checked when the manifest is read and suppression always requires a reason.",
       },
+      problemRules: {
+        type: "array",
+        maxItems: 200,
+        items: { $ref: "#/$defs/problemRule" },
+        description:
+          "The rules the Problems page applies. An entry naming a built-in rule (rules/builtin.json) switches it off or re-grades it, with a reason; any other id is a rule of its own, written in CEL over one subject. Expressions are type-checked when the manifest is read and run in the page over the merged catalog.",
+      },
       plugins: {
         type: "array",
         items: { $ref: "#/$defs/plugin" },
@@ -146,6 +200,7 @@ function compose() {
       },
     },
     $defs: {
+      problemRule: problemRuleSchema(),
       warningPolicy: {
         type: "object",
         additionalProperties: false,
@@ -273,7 +328,7 @@ function compose() {
             description: "What the steps below call this plugin. It need not be the plugin's own name.",
           },
           host: {
-            enum: ["fetch-git", "fetch-bsr", "fetch-csr"],
+            enum: ["fetch-git", "fetch-bsr", "fetch-csr", "fetch-k8s", "fetch-argocd"],
             description:
               "A plugin the host runs inside its own process, because it needs a socket or a git binary (portolan.0008). Only the ones shipped with Portolan can be named.",
           },
@@ -400,3 +455,67 @@ function fail(message) {
   console.error(`portolan schema: ${message}`);
   process.exit(1);
 }
+
+/**
+ * One entry of `problemRules`. Two shapes under one id field: a built-in id
+ * may only be switched, re-graded and explained; any other id is a whole
+ * rule, over one subject, with the expressions the page runs.
+ */
+function problemRuleSchema() {
+  const builtinIds = BUILTIN_RULES.map((rule) => rule.id);
+  const subjectFields = SUBJECT_NAMES.map(
+    (name) => `${name}: ${Object.keys(SUBJECTS[name].schema).join(", ")}`,
+  ).join("; ");
+  const expression = (returns, what) => ({
+    type: "string",
+    minLength: 1,
+    maxLength: 2000,
+    description: `${what} CEL returning ${returns}, over the subject named by \`over\` and \`estate\` (services, contexts, stores, channels, externals). Fields by subject: ${subjectFields}.`,
+  });
+  return {
+    type: "object",
+    additionalProperties: false,
+    required: ["id"],
+    properties: {
+      id: {
+        type: "string",
+        pattern: RULE_ID.source,
+        description: `The rule. One of the built-in ids - ${builtinIds.join(", ")} - to switch or re-grade that rule; any other id declares a rule of its own.`,
+      },
+      enabled: {
+        type: "boolean",
+        default: true,
+        description: "Whether the rule produces rows. A disabled rule needs a reason and stays listed on the Settings page.",
+      },
+      severity: {
+        enum: SEVERITIES,
+        description: "How wrong a row of this rule is. For a built-in rule this replaces the severity its passport was written with.",
+      },
+      reason: {
+        type: "string",
+        minLength: 1,
+        description: "Why the rule is off or re-graded, or, for a rule of your own, why the estate holds it.",
+      },
+      over: {
+        enum: SUBJECT_NAMES,
+        description: "What one row of the rule is about, and what `when` and `message` read.",
+      },
+      when: expression("bool", "The condition: a row exists for every subject where it holds."),
+      message: expression("string", "The note on the row."),
+      peer: expression("string", "The row's far end, when it has one; a service, event or table id links to its page."),
+      title: { type: "string", minLength: 1, description: "The rule's name on the Settings page." },
+      note: { type: "string", minLength: 1, description: "The short words on every row of the rule; the title when absent." },
+      description: { type: "string", description: "What the rule checks and why it matters." },
+      action: { type: "string", description: "What a reader does about a row." },
+    },
+    if: { properties: { id: { enum: builtinIds } } },
+    then: {
+      not: {
+        anyOf: ["over", "when", "message", "peer", "title", "note", "description", "action"].map((key) => ({
+          required: [key],
+        })),
+      },
+    },
+    else: { required: ["over", "when", "message", "title"] },
+  };
+}

package/scripts/trace-trials.mjs

@@ -0,0 +1,176 @@
+// A recording uploaded from the page becomes a file beside the project and a
+// verify step that reads it - nothing else. The pure half of that lives here,
+// where a test can hold it: which step reads a project's recordings, where an
+// upload lands, and what a trial run said about it once the verifier ran.
+//
+// The recording is kept in the repository on purpose (portolan.0014). The
+// catalog is regenerated from files, by anyone, on any machine; a recording
+// held anywhere else would verify a flow once and never again.
+
+import { readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+
+export const TRACE_PLUGIN = "otel";
+export const RECORDINGS_DIR = "telemetry/recordings";
+export const RECORDINGS_GLOB = `${RECORDINGS_DIR}/*.jsonl`;
+export const UPLOAD_LIMIT = 32 * 1024 * 1024;
+
+/** The verify step that reads a project's recordings, or null. */
+export function traceStepFor(manifest, project) {
+  const steps = (manifest.verify ?? []).map((step, index) => ({ step, index }));
+  const mine = steps.filter(({ step }) => step.plugin === TRACE_PLUGIN && step.in === project.root);
+  return mine[0] ?? null;
+}
+
+/**
+ * The manifest with a step that reads the project's recordings: the one it
+ * has, widened to the recordings directory when it does not look there yet,
+ * or a new one after the last verify step. Says whether anything changed.
+ */
+export function manifestWithTraceStep(manifest, project) {
+  const found = traceStepFor(manifest, project);
+  const verify = [...(manifest.verify ?? [])];
+  if (found) {
+    const traces = found.step.options?.traces ?? [];
+    if (traces.includes(RECORDINGS_GLOB)) return { manifest, changed: false, change: "none", step: found.step };
+    const step = { ...found.step, options: { ...found.step.options, traces: [...traces, RECORDINGS_GLOB] } };
+    verify[found.index] = step;
+    return { manifest: { ...manifest, verify }, changed: true, change: "widened", step };
+  }
+  const step = {
+    plugin: TRACE_PLUGIN,
+    in: project.root,
+    out: posix.join(project.root, "portolan"),
+    options: { traces: [RECORDINGS_GLOB], out: "observed.json" },
+  };
+  verify.push(step);
+  return { manifest: { ...manifest, verify }, changed: true, change: "added", step };
+}
+
+/** The step with the names the page was told to map, merged over what it had. */
+export function stepWithMappings(step, { services, events, routes } = {}) {
+  const options = { ...step.options };
+  if (services && Object.keys(services).length) options.services = { ...options.services, ...services };
+  if (events && Object.keys(events).length) options.events = { ...options.events, ...events };
+  if (routes && Object.keys(routes).length) options.routes = { ...options.routes, ...routes };
+  return { ...step, options };
+}
+
+/**
+ * Where an upload lands, relative to the project root: dated, named after
+ * the file it came as, and not on top of a recording already there.
+ */
+export function recordingPath(name, { today = new Date(), taken = () => false } = {}) {
+  const base = String(name ?? "").split(/[\\/]/).pop() ?? "";
+  const stem = base.replace(/\.(jsonl?|ndjson)$/i, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "recording";
+  const date = today.toISOString().slice(0, 10);
+  let candidate = `${RECORDINGS_DIR}/${date}-${stem}.jsonl`;
+  for (let n = 2; taken(candidate); n += 1) candidate = `${RECORDINGS_DIR}/${date}-${stem}-${n}.jsonl`;
+  return candidate;
+}
+
+/**
+ * Says whether the bytes are a recording the verifier can read: OTLP JSON,
+ * one batch per file or one per line, with resourceSpans in it.
+ */
+export function checkRecording(content) {
+  const text = content.toString("utf8");
+  if (!text.trim()) throw new Error("The recording is empty.");
+  let batches = 0;
+  let spans = 0;
+  const read = (value) => {
+    if (!value || typeof value !== "object" || !Array.isArray(value.resourceSpans)) throw new Error("The recording is JSON, but not OTLP: no resourceSpans in it.");
+    batches += 1;
+    for (const rs of value.resourceSpans) for (const ss of rs?.scopeSpans ?? []) spans += (ss?.spans ?? []).length;
+  };
+  try {
+    read(JSON.parse(text));
+  } catch (cause) {
+    if (cause instanceof SyntaxError) {
+      for (const line of text.split("\n")) {
+        if (!line.trim()) continue;
+        let value;
+        try { value = JSON.parse(line); } catch { throw new Error("The recording is not OTLP JSON: a collector's file exporter writes one batch per line."); }
+        read(value);
+      }
+    } else {
+      throw cause;
+    }
+  }
+  if (!spans) throw new Error("The recording has no spans in it.");
+  return { batches, spans };
+}
+
+/** What a verifier's warning is about, so the page can offer the mapping it asks for. */
+export function readVerifyWarning(message) {
+  let m = message.match(/spans from service\.name "([^"]+)" match no service/);
+  if (m) return { kind: "service", name: m[1], message };
+  m = message.match(/(?:publishes|consumes) "([^"]+)", which matches no event/);
+  if (m) return { kind: "event", name: m[1], message };
+  m = message.match(/answers on ([A-Z]* ?\S+), which no interface it provides declares/);
+  if (m) return { kind: "route", name: m[1].trim(), message };
+  m = message.match(/calls ([A-Z]+ \S+) on (\S+), which no service/);
+  if (m) return { kind: "call", name: m[1], message };
+  if (/but the catalog says it goes on/.test(message)) return { kind: "channel", message };
+  return { kind: "other", message };
+}
+
+/**
+ * What the trial run said about the recording: the flows the verifier wrote
+ * with it, and the warnings that name something the page could map.
+ */
+export function summarizeTraceTrial(snapshot, trial, events) {
+  const step = trial.step;
+  const finished = events.find((event) => event.type === "step-finished" && event.phase === "verify" && event.plugin === step.plugin && event.output === step.out && (event.input ?? step.in) === step.in)
+    ?? events.find((event) => event.type === "step-finished" && event.phase === "verify" && event.plugin === step.plugin && event.output === step.out);
+  const warnings = (finished?.warnings ?? []).map(readVerifyWarning);
+  const fragmentName = step.options?.out ?? "observed.json";
+  let fragment = { flows: [] };
+  try { fragment = JSON.parse(readFileSync(join(snapshot, step.out, fragmentName), "utf8")); } catch {}
+  // An example names its recording relative to the repository, the way every
+  // `source` in the catalog does; the upload was laid under the step's input.
+  const recording = posix.join(step.in, trial.recording);
+  const flows = [];
+  for (const flow of fragment.flows ?? []) {
+    const examples = (flow.examples ?? []).filter((example) => example.recording === recording);
+    const steps = [];
+    const walk = (nodes) => {
+      for (const node of nodes ?? []) {
+        if (node.type === "step") steps.push(node);
+        else if (node.type === "alt") for (const branch of node.branches ?? []) walk(branch.steps);
+        else if (node.type === "parallel") for (const branch of node.branches ?? []) walk(branch);
+        else walk(node.steps);
+      }
+    };
+    walk(flow.steps);
+    const shown = new Set(examples.flatMap((example) => example.steps.map((s) => s.step)));
+    const observed = String(flow.slug ?? "").startsWith("observed-");
+    flows.push({
+      id: flow.id,
+      slug: flow.slug,
+      name: flow.name,
+      owner: flow.owner,
+      kind: observed ? "observed" : "declared",
+      inRecording: examples.length > 0,
+      traces: examples.length,
+      verified: steps.filter((s) => s.status === "verified").length,
+      unresolved: steps.filter((s) => s.status === "unresolved").length,
+      added: steps.filter((s) => s.seen && !observed && /^seen\d+$/.test(String(s.id))).length,
+      shown: shown.size,
+      steps: steps.length,
+      examples: (flow.examples ?? []).length,
+    });
+  }
+  flows.sort((a, b) => Number(b.inRecording) - Number(a.inRecording) || a.slug.localeCompare(b.slug));
+  return {
+    project: trial.projectId,
+    recording: trial.recording,
+    stepAdded: trial.stepAdded,
+    stepChange: trial.stepChange ?? (trial.stepAdded ? "added" : "none"),
+    status: finished?.status ?? "failed",
+    spans: trial.spans,
+    flows,
+    warnings,
+    mappings: { services: step.options?.services ?? {}, events: step.options?.events ?? {}, routes: step.options?.routes ?? {} },
+  };
+}

package/scripts/trace-trials.test.mjs

@@ -0,0 +1,142 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { checkRecording, manifestWithTraceStep, readVerifyWarning, recordingPath, stepWithMappings, summarizeTraceTrial, traceStepFor } from "./trace-trials.mjs";
+
+const project = { id: "auth", name: "Auth", root: "examples/auth", context: "auth", service: "auth" };
+
+describe("the step that reads a project's recordings", () => {
+  it("is added after the last verify step when the project has none", () => {
+    const manifest = { sources: ["x/*.json"], projects: [project], verify: [{ plugin: "codeowners", in: ".github", out: "data" }] };
+    const next = manifestWithTraceStep(manifest, project);
+
+    expect(next.changed).toBe(true);
+    expect(next.change).toBe("added");
+    expect(next.manifest.verify).toHaveLength(2);
+    expect(next.step).toEqual({ plugin: "otel", in: "examples/auth", out: "examples/auth/portolan", options: { traces: ["telemetry/recordings/*.jsonl"], out: "observed.json" } });
+    expect(manifest.verify).toHaveLength(1);
+  });
+
+  it("is widened to the recordings directory when it reads elsewhere, and left alone when it already does", () => {
+    const step = { plugin: "otel", in: "examples/auth", out: "examples/auth/portolan", options: { traces: ["telemetry/traces.jsonl"], out: "observed.json", services: { "auth-api": "auth.auth" } } };
+    const manifest = { sources: [], projects: [project], verify: [step] };
+
+    const widened = manifestWithTraceStep(manifest, project);
+    expect(widened.changed).toBe(true);
+    expect(widened.change).toBe("widened");
+    expect(widened.step.options.traces).toEqual(["telemetry/traces.jsonl", "telemetry/recordings/*.jsonl"]);
+    expect(widened.step.options.services).toEqual({ "auth-api": "auth.auth" });
+
+    const again = manifestWithTraceStep(widened.manifest, project);
+    expect(again.changed).toBe(false);
+    expect(again.change).toBe("none");
+    expect(traceStepFor(again.manifest, project)?.index).toBe(0);
+  });
+
+  it("is the project's own, not another project's", () => {
+    const other = { plugin: "otel", in: "examples/shop/cart", out: "examples/shop/cart/portolan", options: { traces: ["telemetry/traces.jsonl"] } };
+    expect(traceStepFor({ verify: [other] }, project)).toBeNull();
+  });
+
+  it("takes the names the page mapped over what it had", () => {
+    const step = { plugin: "otel", in: "x", out: "y", options: { traces: ["a"], events: { "a.B": "x.y.B" } } };
+    const mapped = stepWithMappings(step, { services: { "auth-api": "auth.auth" }, events: { "a.C": "x.y.C" }, routes: { "POST /api/v1/sessions": "login" } });
+    expect(mapped.options).toEqual({ traces: ["a"], events: { "a.B": "x.y.B", "a.C": "x.y.C" }, services: { "auth-api": "auth.auth" }, routes: { "POST /api/v1/sessions": "login" } });
+    expect(stepWithMappings(step, {})).toEqual(step);
+  });
+});
+
+describe("where an upload lands", () => {
+  const today = new Date("2026-09-12T10:00:00Z");
+
+  it("is dated, named after the file, and never on top of another", () => {
+    expect(recordingPath("Login Traces.JSONL", { today })).toBe("telemetry/recordings/2026-09-12-login-traces.jsonl");
+    expect(recordingPath("/tmp/export/traces.json", { today })).toBe("telemetry/recordings/2026-09-12-traces.jsonl");
+    expect(recordingPath("", { today })).toBe("telemetry/recordings/2026-09-12-recording.jsonl");
+    const taken = new Set(["telemetry/recordings/2026-09-12-traces.jsonl", "telemetry/recordings/2026-09-12-traces-2.jsonl"]);
+    expect(recordingPath("traces.jsonl", { today, taken: (candidate) => taken.has(candidate) })).toBe("telemetry/recordings/2026-09-12-traces-3.jsonl");
+  });
+});
+
+describe("what an upload has to be", () => {
+  const batch = (spans) => JSON.stringify({ resourceSpans: [{ resource: { attributes: [] }, scopeSpans: [{ spans }] }] });
+  const span = { traceId: "t", spanId: "s", name: "GET /", kind: 2 };
+
+  it("reads one value or one per line", () => {
+    expect(checkRecording(Buffer.from(batch([span])))).toEqual({ batches: 1, spans: 1 });
+    expect(checkRecording(Buffer.from(`${batch([span])}\n${batch([span, span])}\n`))).toEqual({ batches: 2, spans: 3 });
+  });
+
+  it("refuses what the verifier could not read, and says why", () => {
+    expect(() => checkRecording(Buffer.from(""))).toThrow(/empty/);
+    expect(() => checkRecording(Buffer.from("not json"))).toThrow(/not OTLP JSON/);
+    expect(() => checkRecording(Buffer.from('{"traces":[]}'))).toThrow(/no resourceSpans/);
+    expect(() => checkRecording(Buffer.from(batch([])))).toThrow(/no spans/);
+  });
+});
+
+describe("what a verifier's warning is about", () => {
+  it("names the service, event or route the page could map", () => {
+    expect(readVerifyWarning('spans from service.name "auth-api" match no service in the catalog; name it under `services` to say which one it is')).toMatchObject({ kind: "service", name: "auth-api" });
+    expect(readVerifyWarning('publishes "auth.Ended", which matches no event of its own in the catalog; name it under `events`')).toMatchObject({ kind: "event", name: "auth.Ended" });
+    expect(readVerifyWarning('consumes "auth.Ended", which matches no event in the catalog; name it under `events`')).toMatchObject({ kind: "event", name: "auth.Ended" });
+    expect(readVerifyWarning("answers on GET /v1/health, which no interface it provides declares; the flow opens on the route rather than an operation")).toMatchObject({ kind: "route", name: "GET /v1/health" });
+    expect(readVerifyWarning("calls GET /v1/profiles/42 on profile, which no service in the catalog answers on; the hop is unresolved")).toMatchObject({ kind: "call", name: "GET /v1/profiles/42" });
+    expect(readVerifyWarning('publishes "a" on "x", but the catalog says it goes on "y"')).toMatchObject({ kind: "channel" });
+    expect(readVerifyWarning("something else")).toEqual({ kind: "other", message: "something else" });
+  });
+});
+
+describe("what a trial run said about the recording", () => {
+  const roots = [];
+  afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+
+  it("lists the flows the recording showed first, with what it raised and added", () => {
+    const snapshot = mkdtempSync(join(tmpdir(), "portolan-trace-trial-"));
+    roots.push(snapshot);
+    mkdirSync(join(snapshot, "examples/auth/portolan"), { recursive: true });
+    const recording = "telemetry/recordings/2026-09-12-login.jsonl";
+    const named = `examples/auth/${recording}`;
+    writeFileSync(join(snapshot, "examples/auth/portolan/observed.json"), JSON.stringify({
+      flows: [
+        {
+          id: "flow.auth-login", slug: "auth-login", name: "Login", owner: "auth", participants: [],
+          steps: [
+            { type: "step", id: "s1", status: "verified", seen: { traces: 1 } },
+            { type: "step", id: "s2", status: "declared" },
+            { type: "alt", id: "alt3", branches: [{ title: "blocked", steps: [{ type: "step", id: "seen1", status: "unresolved", seen: { traces: 1 } }] }] },
+          ],
+          examples: [{ id: `${recording}#t1`, recording: named, traceId: "t1", durationMs: 1, steps: [{ step: "s1", durationMs: 1 }, { step: "seen1", durationMs: 1 }] }],
+        },
+        {
+          id: "flow.observed-auth-get-v1-health", slug: "observed-auth-get-v1-health", name: "Observed: GET /v1/health", owner: "auth", participants: [],
+          steps: [{ type: "step", id: "s1", status: "verified", seen: { traces: 3 } }],
+          examples: [{ id: "telemetry/traces.jsonl#t9", recording: "examples/auth/telemetry/traces.jsonl", traceId: "t9", durationMs: 1, steps: [] }],
+        },
+      ],
+    }));
+    const step = { plugin: "otel", in: "examples/auth", out: "examples/auth/portolan", options: { traces: ["telemetry/recordings/*.jsonl"], out: "observed.json", services: { "auth-api": "auth.auth" } } };
+    const events = [
+      { type: "step-finished", phase: "extract", plugin: "go-domain", output: "examples/auth/portolan", status: "ok", warnings: ["ignored"] },
+      { type: "step-finished", phase: "verify", plugin: "otel", input: "examples/auth", output: "examples/auth/portolan", status: "warning", warnings: ['spans from service.name "risk" match no service in the catalog; name it under `services` to say which one it is'] },
+    ];
+
+    const summary = summarizeTraceTrial(snapshot, { projectId: "auth", root: "examples/auth", recording, step, stepAdded: true, stepChange: "widened", spans: 7 }, events);
+
+    expect(summary).toMatchObject({ project: "auth", recording, stepAdded: true, stepChange: "widened", status: "warning", spans: 7, mappings: { services: { "auth-api": "auth.auth" }, events: {}, routes: {} } });
+    expect(summary.warnings).toEqual([{ kind: "service", name: "risk", message: events[1].warnings[0] }]);
+    expect(summary.flows.map((flow) => flow.slug)).toEqual(["auth-login", "observed-auth-get-v1-health"]);
+    expect(summary.flows[0]).toMatchObject({ kind: "declared", inRecording: true, traces: 1, verified: 1, unresolved: 1, added: 1, shown: 2, steps: 3, examples: 1 });
+    expect(summary.flows[1]).toMatchObject({ kind: "observed", inRecording: false, traces: 0, verified: 1, added: 0 });
+  });
+
+  it("is a failed, empty summary when the verifier wrote nothing", () => {
+    const snapshot = mkdtempSync(join(tmpdir(), "portolan-trace-trial-"));
+    roots.push(snapshot);
+    const step = { plugin: "otel", in: "x", out: "x/portolan", options: { traces: [] } };
+    const summary = summarizeTraceTrial(snapshot, { projectId: "p", root: "x", recording: "telemetry/recordings/a.jsonl", step, stepAdded: false, spans: 1 }, []);
+    expect(summary).toMatchObject({ status: "failed", flows: [], warnings: [] });
+  });
+});