@shortlink-org/portolan 0.3.0 → 0.4.0

package/src/lib/shape.ts

@@ -26,6 +26,7 @@ import type {
 } from "../catalog";
 import { aggregateBlocks, blockFields, enumsOf } from "../catalog";
 import type { DefUsage } from "./derive";
+import { ruleMarks } from "./rules";
 
 /** How many of the base type a field holds. */
 export type Cardinality = "one" | "many" | "map";
@@ -336,13 +337,19 @@ export interface FieldChange {
   change: Change;
   /** The type the field had in the previous version, when it changed. */
   from?: string;
+  /**
+   * The rules the field had in the previous version, as the marks read -
+   * "required, ≤ 8 chars" - when this version changed them; "" when it had
+   * none. The row itself shows what they are now.
+   */
+  rulesFrom?: string;
 }
 
 /**
  * What a version did to the schema: the fields it added, the ones whose
- * type it changed, and - by name, since they are no longer in the version's
- * own list - the ones it dropped. The first version changes nothing: there
- * is nothing before it to differ from.
+ * type or rules it changed, and - by name, since they are no longer in the
+ * version's own list - the ones it dropped. The first version changes
+ * nothing: there is nothing before it to differ from.
  */
 export function schemaChanges(
   event: Event,
@@ -360,9 +367,14 @@ export function schemaChanges(
   const now = new Set(current.fields.map((f) => f.name));
   for (const field of current.fields) {
     const was = before.get(field.name);
-    if (!was) byField.set(field.name, { change: "new" });
-    else if (was.type !== field.type)
-      byField.set(field.name, { change: "changed", from: was.type });
+    if (!was) {
+      byField.set(field.name, { change: "new" });
+      continue;
+    }
+    const change: FieldChange = { change: "changed" };
+    if (was.type !== field.type) change.from = was.type;
+    if (!sameRules(was, field)) change.rulesFrom = ruleMarks(was).map((m) => m.text).join(", ");
+    if (change.from !== undefined || change.rulesFrom !== undefined) byField.set(field.name, change);
   }
   for (const field of prev.fields) {
     if (!now.has(field.name)) removed.push(field);
@@ -370,6 +382,18 @@ export function schemaChanges(
   return { byField, removed };
 }
 
+/**
+ * Whether two versions of a field ask the same of its value. The order the
+ * rules are listed in is the source's, not a fact about the value, so it
+ * is not a difference.
+ */
+function sameRules(a: Field, b: Field): boolean {
+  if (Boolean(a.required) !== Boolean(b.required)) return false;
+  const key = (field: Field) =>
+    (field.rules ?? []).map((r) => `${r.name}=${r.value ?? ""}`).sort().join("\n");
+  return key(a) === key(b);
+}
+
 // ---------------------------------------------------------------------------
 // An enum and a lifecycle.
 // ---------------------------------------------------------------------------

package/src/lib/tech.ts

@@ -30,6 +30,7 @@ import {
   siApachepulsar,
   siArgo,
   siAuth0,
+  siBackstage,
   siBun,
   siC,
   siCelery,
@@ -37,6 +38,7 @@ import {
   siClickhouse,
   siClojure,
   siCloudflare,
+  siConfluence,
   siCockroachlabs,
   siConsul,
   siCouchbase,
@@ -93,7 +95,9 @@ import {
   siLinkerd,
   siLua,
   siMariadb,
+  siMarkdown,
   siMeilisearch,
+  siMermaid,
   siMinio,
   siMongodb,
   siMqtt,
@@ -107,6 +111,7 @@ import {
   siNginx,
   siNodedotjs,
   siNomad,
+  siNotion,
   siNpm,
   siOllama,
   siOpenapiinitiative,
@@ -346,6 +351,11 @@ export const TECH_MARKS: readonly TechMark[] = [
   mark(siJenkins),
   mark(siArgo, "Argo CD", "ArgoCD"),
 
+  // Where a team writes. Not read off a manifest; the marks are for the
+  // reader-side integrations that open the wiki from a page.
+  mark(siConfluence),
+  mark(siNotion),
+
   // Observability.
   mark(siOpentelemetry, "otel"),
   mark(siPrometheus),
@@ -374,6 +384,11 @@ export const TECH_MARKS: readonly TechMark[] = [
   mark(siJest),
   mark(siVitest),
   mark(siCypress),
+
+  // What the generators write to.
+  mark(siMarkdown),
+  mark(siMermaid),
+  mark(siBackstage),
 ];
 
 const BY_KEY: ReadonlyMap<string, TechGlyph> = (() => {
@@ -417,5 +432,6 @@ export const STORE_KIND_GLYPH: Record<StoreKind, TechGlyph | null> = {
   clickhouse: techGlyph("clickhouse"),
   // simple-icons was asked to drop Amazon's marks, S3's among them.
   s3: null,
+  dynamodb: null,
   other: null,
 };

package/src/lib/trace-project.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+
+import { projectForFlow, projectsForFlow } from "./trace-project";
+
+const projects = [
+  { id: "auth", name: "Auth", root: "examples/auth", context: "auth", service: "auth" },
+  { id: "shop-cart", name: "Cart", root: "examples/shop/cart", context: "shop", service: "cart" },
+  { id: "shop-oms", name: "OMS", root: "examples/shop/oms", group: "shop", component: "oms" },
+];
+
+const flow = (owner: string, ...services: string[]) => ({
+  owner,
+  participants: [
+    { id: "client", kind: "actor" as const, context: null },
+    ...services.map((id) => ({ id, kind: "service" as const, context: id.split(".")[0] ?? null })),
+    { id: "bus", kind: "broker" as const, context: null },
+  ],
+});
+
+describe("which project a recording of a flow belongs to", () => {
+  it("is the one project in the flow's context", () => {
+    expect(projectForFlow(projects, flow("auth", "auth.auth"))?.id).toBe("auth");
+  });
+
+  it("is the project whose service the flow runs through when the context has several", () => {
+    expect(projectForFlow(projects, flow("shop", "shop.oms", "shop.pricing"))?.id).toBe("shop-oms");
+    expect(projectsForFlow(projects, flow("shop", "shop.cart")).map((p) => p.id)).toEqual(["shop-cart", "shop-oms"]);
+  });
+
+  it("is nobody's when the context has no project, or two the flow runs through", () => {
+    expect(projectForFlow(projects, flow("payments", "payments.ledger"))).toBeNull();
+    expect(projectForFlow(projects, flow("shop", "shop.cart", "shop.oms"))).toBeNull();
+  });
+});

package/src/lib/trace-project.ts

@@ -0,0 +1,50 @@
+// Which project a recording of a flow belongs to.
+//
+// A recording is kept beside the project whose verify step reads it, and a
+// flow says which context owns it - one level up from a project. The project
+// is the one in that context whose service the flow runs through; when the
+// context has one project, that one; otherwise the page has to ask.
+
+import type { Flow } from "../catalog";
+import type { SetupProject } from "./setup-info";
+
+/** The projects a flow's recording could be kept under, the likeliest first. */
+export function projectsForFlow(
+  projects: readonly SetupProject[],
+  flow: Pick<Flow, "owner" | "participants">,
+): SetupProject[] {
+  const inContext = projects.filter(
+    (project) => (project.group ?? project.context) === flow.owner,
+  );
+  const services = new Set(
+    flow.participants
+      .filter((p) => p.kind === "service" && p.context === flow.owner)
+      .map((p) => p.id.split(".").slice(1).join(".")),
+  );
+  const runsThrough = (project: SetupProject) =>
+    services.has(project.component ?? project.service ?? "");
+
+  return [...inContext].sort(
+    (a, b) => Number(runsThrough(b)) - Number(runsThrough(a)) || a.id.localeCompare(b.id),
+  );
+}
+
+/** The one project a recording of the flow goes to, or null when it has to be asked. */
+export function projectForFlow(
+  projects: readonly SetupProject[],
+  flow: Pick<Flow, "owner" | "participants">,
+): SetupProject | null {
+  const candidates = projectsForFlow(projects, flow);
+  if (candidates.length === 1) return candidates[0]!;
+  if (candidates.length === 0) return null;
+  const services = new Set(
+    flow.participants
+      .filter((p) => p.kind === "service" && p.context === flow.owner)
+      .map((p) => p.id.split(".").slice(1).join(".")),
+  );
+  const through = candidates.filter((project) =>
+    services.has(project.component ?? project.service ?? ""),
+  );
+
+  return through.length === 1 ? through[0]! : null;
+}

package/src/lib/use-problems.ts

@@ -0,0 +1,23 @@
+// The problems of the live catalog, for a component.
+//
+// Five places show the same list - the page, the sidebar badge, the overview,
+// the landing's demo, the rules table - and each used to compute it once on
+// mount. Now the list depends on the rules in force, which the Settings page
+// changes under a running app, so the computation subscribes to them and the
+// five places re-render together when a switch is flipped.
+
+import { useMemo } from "react";
+import { catalog, index } from "../data";
+import { evaluateProblems } from "./all-problems";
+import type { Problem } from "./derive";
+import { useProblemRules } from "./problem-rules";
+import type { RuleEvaluation } from "./problem-rules";
+
+export function useProblemEvaluation(): RuleEvaluation {
+  const rules = useProblemRules();
+  return useMemo(() => evaluateProblems(catalog, index, rules), [rules]);
+}
+
+export function useProblems(): Problem[] {
+  return useProblemEvaluation().problems;
+}

package/src/lib/warnings.test.ts

@@ -31,6 +31,15 @@ describe("warning diagnostics", () => {
     ]);
   });
 
+  it("keeps one rule across the wordings the plugins emit for it", () => {
+    const rules = [
+      "calls ledger.v1 and the manifest names no peer for it; add it under `peers` to say which service answers, until then the calls are unresolved",
+      "src/app.rs: port `clock: Clock` is neither a domain port, a use case nor a client; its calls are left out of the flow",
+      "bus/router.go:12:3: Watermill handler orders is registered on topic `cfg.Topic`, which this reader cannot resolve to a literal, a constant, a config default or a caller's argument; the handler is kept with its topic unresolved",
+    ].map((message) => warningDiagnostic({ plugin: "x", message }).rule);
+    expect(rules).toEqual(["catalog.unmapped-proto-peer", "flow.unknown-port", "watermill.unresolved-topic"]);
+  });
+
   it("marks read and parse failures as errors and expected absence as info", () => {
     expect(warningDiagnostic({ plugin: "sql", message: "schema.sql could not be parsed" }).severity).toBe("error");
     expect(warningDiagnostic({ plugin: "river", message: "root: no River jobs were found" }).severity).toBe("info");

package/src/lib/warnings.ts

@@ -68,7 +68,7 @@ const RULES: RuleDefinition[] = [
   },
   {
     id: "catalog.unmapped-proto-peer",
-    matches: /\bmanifest names no peer for that package\b/i,
+    matches: /\bmanifest names no peer for (?:that package|it)\b/i,
     severity: "warning",
     action: "Map the protobuf package under peers, or declare it under externals.",
   },
@@ -80,7 +80,7 @@ const RULES: RuleDefinition[] = [
   },
   {
     id: "flow.unknown-port",
-    matches: /\bis neither a domain port nor a use case\b/i,
+    matches: /\bis neither a domain port(?:,| nor) a use case\b/i,
     severity: "warning",
     action: "Model this dependency as a domain port or use case, or accept that its calls stay outside the flow.",
   },
@@ -102,12 +102,6 @@ const RULES: RuleDefinition[] = [
     severity: "warning",
     action: "Choose an existing concrete model for the application's aggregates option.",
   },
-  {
-    id: "django.ambiguous-aggregate-root",
-    matches: /\bmodels to choose from: name the root in the aggregates option\b/i,
-    severity: "warning",
-    action: "Choose the aggregate root explicitly in the django-domain aggregates option.",
-  },
   {
     id: "django.unknown-http-verb",
     matches: /\bmounted as an HTTP view, but no HTTP verb is declared\b/i,
@@ -122,7 +116,7 @@ const RULES: RuleDefinition[] = [
   },
   {
     id: "watermill.unresolved-topic",
-    matches: /\bWatermill .+ topic could not be resolved\b/i,
+    matches: /\bWatermill .+\btopic (?:generator could not be resolved|unresolved)\b/i,
     severity: "warning",
     action: "Use a literal, constant, or configuration default for the Watermill topic.",
   },
@@ -152,10 +146,16 @@ const RULES: RuleDefinition[] = [
   },
   {
     id: "source.offline-cache",
-    matches: /\bnot fetched \(offline\)\b/i,
+    matches: /\bnot (?:fetched|read) \(offline\)/i,
     severity: "info",
     action: "Regenerate with network access when the vendored copy must be refreshed.",
   },
+  {
+    id: "source.unreachable",
+    matches: /\bnot (?:fetched|read) \((?!offline\))/i,
+    severity: "warning",
+    action: "The far end could not be reached and the committed copy was used; check the server and the credential, then regenerate.",
+  },
   {
     id: "source.unpinned",
     matches: /\bnot pinned\b/i,

package/src/likec4/ids.test.ts

@@ -9,6 +9,8 @@ import {
   CONTAINERS_VIEW,
   LANDSCAPE_VIEW,
   allViewIds,
+  deployedServices,
+  environmentsOf,
   contextViewId,
   eventFqn,
   flowCrossViewId,
@@ -100,14 +102,16 @@ describe("view ids", () => {
     expect(new Set(ids).size).toBe(ids.length);
   });
 
-  it("covers the landscape, the containers, every context, both views of every service and both of every flow", () => {
+  it("covers the landscape, the containers, every context, both views of every service, both of every flow, every environment and every deployed service", () => {
     const ids = allViewIds(catalog);
     const services = catalog.contexts.flatMap((c) => c.services);
     expect(ids).toHaveLength(
       2 +
         catalog.contexts.length +
         services.length * 2 +
-        catalog.flows.length * 2,
+        catalog.flows.length * 2 +
+        environmentsOf(catalog).length +
+        deployedServices(catalog).length,
     );
     // The three C4 levels: the estate, its containers, a context, and a
     // service opened up.

package/src/likec4/ids.ts

@@ -9,6 +9,7 @@ import type {
   Participant,
   Service,
 } from "../catalog";
+import { allDeployments, deploys, environmentOf } from "../catalog";
 import reserved from "./reserved.json";
 
 /**
@@ -97,6 +98,42 @@ export const flowViewId = (flow: Flow | string): string =>
 export const flowCrossViewId = (flow: Flow | string): string =>
   `${flowViewId(flow)}_cross`;
 
+/**
+ * Where the services run, one environment at a time: the clusters and
+ * namespaces of the environment as frames, an instance of every service the
+ * snapshot places there, and between the instances what the model declares
+ * between their services (portolan.0012).
+ */
+export const deploymentViewId = (environment: string): string =>
+  `deploy_${safeId(environment)}`;
+
+/** One service, every place it runs: its instances, with the frames around each. */
+export const serviceDeployViewId = (service: Service | string): string =>
+  `deploy_svc_${safeId(typeof service === "string" ? service : service.id)}`;
+
+/**
+ * The environments the snapshot places services in, sorted. A deployment of
+ * a repository no service claims places nothing and names no environment
+ * here: an environment with nothing of the estate in it is not a picture.
+ */
+export function environmentsOf(catalog: Catalog): string[] {
+  const services = catalog.contexts.flatMap((context) => context.services);
+  const found = new Set<string>();
+  for (const deployment of allDeployments(catalog)) {
+    if (!services.some((service) => deploys(deployment, service))) continue;
+    found.add(environmentOf(deployment));
+  }
+  return [...found].sort();
+}
+
+/** The services the snapshot places somewhere, in catalog order. */
+export function deployedServices(catalog: Catalog): Service[] {
+  const deployments = allDeployments(catalog);
+  return catalog.contexts
+    .flatMap((context) => context.services)
+    .filter((service) => deployments.some((d) => deploys(d, service)));
+}
+
 /** Every view id the generator is expected to emit, in a stable order. */
 export function allViewIds(catalog: Catalog): string[] {
   const out: string[] = [LANDSCAPE_VIEW, CONTAINERS_VIEW];
@@ -111,5 +148,11 @@ export function allViewIds(catalog: Catalog): string[] {
     out.push(flowViewId(flow));
     out.push(flowCrossViewId(flow));
   }
+  for (const environment of environmentsOf(catalog)) {
+    out.push(deploymentViewId(environment));
+  }
+  for (const service of deployedServices(catalog)) {
+    out.push(serviceDeployViewId(service));
+  }
   return out;
 }

package/src/main.tsx

@@ -3,6 +3,29 @@ import { createRoot } from "react-dom/client";
 import "./index.css";
 import { App } from "./app/App";
 
+// A deploy replaces every hashed chunk at once, but a static host may keep
+// serving the old index.html from cache for a while (GitLab Pages caches every
+// file for ten minutes and lets a project set no headers of its own). A tab
+// that opened on the old page then asks for chunks that no longer exist, the
+// lazy import fails, and the reader sees an empty canvas. Vite reports that
+// failure here before it throws; one reload revalidates the document and
+// picks up the new names. The guard is keyed by the chunk that failed, so a
+// chunk that is truly missing cannot reload the page forever.
+const RELOADED = "portolan:reloaded-for";
+window.addEventListener("vite:preloadError", (event) => {
+  const failed = String((event as Event & { payload?: unknown }).payload ?? "");
+  let already = "";
+  try {
+    already = sessionStorage.getItem(RELOADED) ?? "";
+    sessionStorage.setItem(RELOADED, failed);
+  } catch {
+    // Storage may be unavailable; a single reload is still worth trying.
+  }
+  if (already === failed) return;
+  event.preventDefault();
+  window.location.reload();
+});
+
 const container = document.getElementById("root");
 if (!container) throw new Error("#root is missing from index.html");
 

package/src/merge-deployments.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+import type { Deployment } from "./catalog";
+import { mergeCatalogs } from "./merge";
+import type { CatalogSource } from "./merge";
+
+function source(path: string, deployments: Deployment[]): CatalogSource {
+  return {
+    path,
+    catalog: {
+      generatedAt: "",
+      commit: "",
+      contexts: [],
+      defs: {},
+      flows: [],
+      adrs: [],
+      deployments,
+    },
+  };
+}
+
+const manifest = (over: Partial<Deployment> = {}): Deployment => ({
+  id: "argocd/shop-cart-prod",
+  name: "shop-cart-prod",
+  project: "shop",
+  environment: "prod",
+  cluster: "in-cluster",
+  namespace: "shop",
+  repo: "github.com/acme/gitops",
+  path: "envs/prod/shop/cart",
+  targetRevision: "main",
+  revision: "",
+  tool: "kustomize",
+  url: "",
+  service: "shop.cart",
+  images: ["ghcr.io/acme/cart:2.1.0"],
+  basis: "manifest",
+  ...over,
+});
+
+const api = (over: Partial<Deployment> = {}): Deployment => ({
+  id: "argocd/shop-cart-prod",
+  name: "shop-cart-prod",
+  project: "shop",
+  environment: "prod",
+  cluster: "in-cluster",
+  namespace: "shop",
+  repo: "github.com/acme/gitops",
+  path: "envs/prod/shop/cart",
+  targetRevision: "main",
+  revision: "a".repeat(40),
+  tool: "kustomize",
+  url: "https://argocd.example.com/applications/argocd/shop-cart-prod",
+  images: ["ghcr.io/acme/cart:2.1.0", "redis:7"],
+  basis: "api",
+  ...over,
+});
+
+describe("the merge lays the tree under the deployer", () => {
+  it("folds a manifest row and an api row into one that the deployer shapes and the tree fills, with no drift when they agree", () => {
+    const { catalog, conflicts } = mergeCatalogs([
+      source("gitops/portolan/argocd.json", [manifest()]),
+      source("argocd/argocd.apps.json", [api({ service: undefined })]),
+    ]);
+    expect(conflicts).toEqual([]);
+    expect(catalog.deployments).toHaveLength(1);
+    const [row] = catalog.deployments!;
+    expect(row).toMatchObject({
+      basis: "both",
+      revision: "a".repeat(40),
+      url: "https://argocd.example.com/applications/argocd/shop-cart-prod",
+      // The labels the tree carries place the row when the deployer's did not.
+      service: "shop.cart",
+      // What runs, not what is pinned: the base's redis is running too.
+      images: ["ghcr.io/acme/cart:2.1.0", "redis:7"],
+    });
+    expect(row?.drift).toBeUndefined();
+  });
+
+  it("keeps the tree's word as drift where the deployer says otherwise, whichever arrives first", () => {
+    const tree = manifest({ targetRevision: "release-2.1", images: ["ghcr.io/acme/cart:2.1.0"], namespace: "shop" });
+    const cluster = api({ targetRevision: "main", images: ["ghcr.io/acme/cart:2.0.9"], namespace: "shop-old" });
+    for (const order of [[tree, cluster], [cluster, tree]]) {
+      const { catalog, conflicts } = mergeCatalogs([
+        source("first.json", [order[0]!]),
+        source("second.json", [order[1]!]),
+      ]);
+      expect(conflicts).toEqual([]);
+      const [row] = catalog.deployments!;
+      expect(row?.basis).toBe("both");
+      expect(row?.targetRevision).toBe("main");
+      expect(row?.namespace).toBe("shop-old");
+      expect(row?.drift).toEqual({
+        namespace: "shop",
+        targetRevision: "release-2.1",
+        images: ["ghcr.io/acme/cart:2.1.0"],
+      });
+    }
+  });
+
+  it("does not call a pinned image drift when nothing runs yet, and shows the pinned ones instead", () => {
+    const { catalog } = mergeCatalogs([
+      source("tree.json", [manifest()]),
+      source("api.json", [api({ images: undefined, revision: "" })]),
+    ]);
+    const [row] = catalog.deployments!;
+    expect(row?.images).toEqual(["ghcr.io/acme/cart:2.1.0"]);
+    expect(row?.drift).toBeUndefined();
+  });
+
+  it("leaves a row only one source spoke for as it was, and reports two of one basis as a collision", () => {
+    // Sources are read in path order, so the names say who comes first.
+    const { catalog, conflicts } = mergeCatalogs([
+      source("a-tree.json", [manifest()]),
+      source("b-tree.json", [manifest({ path: "elsewhere" })]),
+      source("c-api.json", [api()]),
+      source("d-api.json", [api({ revision: "b".repeat(40) })]),
+    ]);
+    expect(catalog.deployments).toHaveLength(1);
+    expect(catalog.deployments?.[0]?.revision).toBe("a".repeat(40));
+    expect(conflicts.map((c) => c.path)).toEqual(["b-tree.json", "d-api.json"]);
+    expect(conflicts[0]?.message).toContain("declared here and in a-tree.json");
+    expect(conflicts[1]?.message).toContain("listed here and in c-api.json");
+
+    const alone = mergeCatalogs([source("tree.json", [manifest()])]);
+    expect(alone.catalog.deployments?.[0]).toEqual(manifest());
+  });
+});

package/src/merge.test.ts

@@ -858,6 +858,88 @@ describe("a second source that has seen the flow run", () => {
     expect(first?.type === "step" ? first.status : "").toBe("declared");
   });
 
+  it("takes a hop a recording showed that the code does not declare, where the recording put it", () => {
+    const seen = {
+      type: "step" as const,
+      id: "seen1",
+      from: "auth.auth",
+      to: "profile",
+      kind: "rpc" as const,
+      label: "GET /v1/profiles/42",
+      status: "unresolved" as const,
+      seen: { traces: 2 },
+    };
+    const lane = { id: "profile", kind: "unknown" as const, context: null, label: "profile" };
+    const example = { id: "telemetry/traces.jsonl#t1", recording: "telemetry/traces.jsonl", traceId: "t1", durationMs: 2.5, steps: [{ step: "s1", durationMs: 2.5 }] };
+    const merged = mergeCatalogs([
+      source("a.json", { flows: [flow([step("s1", "declared"), step("s2", "declared")])] }),
+      source("b.json", {
+        flows: [{
+          ...flow([{ ...step("s1", "verified"), seen: { traces: 2 } }, seen, step("s2", "declared")]),
+          participants: [...flow([]).participants, lane],
+          examples: [example],
+        }],
+      }),
+    ]);
+
+    expect(merged.conflicts).toEqual([]);
+    const out = merged.catalog.flows[0]!;
+    expect(out.steps.map((s) => (s.type === "step" ? `${s.id}:${s.status}` : s.type))).toEqual(["s1:verified", "seen1:unresolved", "s2:declared"]);
+    expect(out.steps[0]?.type === "step" ? out.steps[0].seen : undefined).toEqual({ traces: 2 });
+    expect(out.participants.map((p) => p.id)).toEqual(["client", "auth.auth", "profile"]);
+    expect(out.examples).toEqual([example]);
+  });
+
+  it("takes a frame where the recordings parted, and not a frame the code did not write", () => {
+    const seenStep = (id: string, label: string) => ({ ...step(id, "verified" as const), label, seen: { traces: 1 } });
+    const frame = {
+      type: "alt" as const,
+      id: "seen-alt1",
+      branches: [
+        { title: "getUser", steps: [seenStep("seen1", "getUser")], seen: { traces: 1 } },
+        { title: "otherwise", steps: [], seen: { traces: 1 } },
+      ],
+    };
+    const merged = mergeCatalogs([
+      source("a.json", { flows: [flow([step("s1", "declared"), step("s2", "declared")])] }),
+      source("b.json", { flows: [flow([step("s1", "verified"), frame, step("s2", "declared")])] }),
+    ]);
+    expect(merged.conflicts).toEqual([]);
+    expect(merged.catalog.flows[0]?.steps.map((s) => s.id)).toEqual(["s1", "seen-alt1", "s2"]);
+
+    const unseen = { ...frame, branches: [{ title: "x", steps: [step("x1", "verified")] }] };
+    const refused = mergeCatalogs([
+      source("a.json", { flows: [flow([step("s1", "declared")])] }),
+      source("b.json", { flows: [flow([step("s1", "verified"), unseen])] }),
+    ]);
+    expect(refused.conflicts).toHaveLength(1);
+  });
+
+  it("is still a conflict when a lane the code declared is missing or a declared step is", () => {
+    const fewerLanes = mergeCatalogs([
+      source("a.json", { flows: [flow([step("s1", "declared")])] }),
+      source("b.json", { flows: [{ ...flow([step("s1", "verified")]), participants: [{ id: "client", kind: "actor" as const, context: null }] }] }),
+    ]);
+    expect(fewerLanes.conflicts).toHaveLength(1);
+
+    const fewerSteps = mergeCatalogs([
+      source("a.json", { flows: [flow([step("s1", "declared"), step("s2", "declared")])] }),
+      source("b.json", { flows: [flow([step("s1", "verified")])] }),
+    ]);
+    expect(fewerSteps.conflicts).toHaveLength(1);
+  });
+
+  it("keeps an example it already has when a second recording says it again", () => {
+    const example = (id: string) => ({ id, recording: "t.jsonl", traceId: id, durationMs: 1, steps: [] });
+    const merged = mergeCatalogs([
+      source("a.json", { flows: [{ ...flow([step("s1", "declared")]), examples: [example("a")] }] }),
+      source("b.json", { flows: [{ ...flow([step("s1", "verified")]), examples: [example("a"), example("b")] }] }),
+    ]);
+
+    expect(merged.conflicts).toEqual([]);
+    expect(merged.catalog.flows[0]?.examples?.map((e) => e.id)).toEqual(["a", "b"]);
+  });
+
   it("lets verified win for a consumer and a call declared twice", () => {
     const withEdges = (status: "declared" | "verified") => {
       const ctx = context("shop", ["shop.oms"]);