@shortlink-org/portolan 0.2.4 → 0.4.0

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"]);

package/src/merge.ts

@@ -15,8 +15,12 @@
 //    context's name is a fact about the estate that belongs on the Problems
 //    page, next to the other things that are true and unfortunate.
 
+import { deploymentBasis } from "./catalog-model.ts";
 import type {
   Aggregate,
+  Deployment,
+  DeploymentBasis,
+  DeploymentDrift,
   Alt,
   AltBranch,
   Block,
@@ -42,13 +46,14 @@ import type {
  * A catalog as a FILE may carry it, which is not quite a catalog as a reader
  * gets one: the two stamps are optional here and required downstream.
  *
- * The host stamps what it generates, from the last commit that touched the
- * input the fragment was read from. A file nobody generates - the estate's
- * hand-written facts - is stamped by nobody, and a provenance typed in by hand
- * is a claim no process keeps true: it stays where it was typed while the
- * estate moves on, and being the oldest stamp in the corpus it then dates the
- * whole merged catalog. So a source is allowed to carry no stamp at all, and
- * saying nothing is treated as what it is - an absence of evidence, which
+ * A fragment carries no stamp of its own (portolan.0010). When it last
+ * changed, and in which commit, is what the history of the checkout says,
+ * and whoever reads the file asks the history and hands the answer over
+ * beside it. A file may still say something - a fragment written before
+ * portolan.0010 does - and that is taken only when nobody read the history.
+ * A provenance typed in by hand is a claim no process keeps true, so a source
+ * that says nothing and was read outside any history is stamped by nobody,
+ * and saying nothing is treated as what it is - an absence of evidence, which
  * drops out of the merge rather than voting in it.
  */
 export type SourceCatalog = Omit<Catalog, "generatedAt" | "commit"> &
@@ -59,6 +64,12 @@ export interface CatalogSource {
   /** Where it was read from, as a reader would type it. */
   path: string;
   catalog: SourceCatalog;
+  /**
+   * When the file last changed and in which commit, as the reader found out
+   * from the history of the checkout (portolan.0010). Left out when there
+   * was no history to ask, and the file then speaks for itself.
+   */
+  stamp?: Pick<SourceStamp, "generatedAt" | "commit">;
 }
 
 /**
@@ -114,14 +125,16 @@ export function mergeCatalogs(sources: CatalogSource[]): MergeResult {
   const terms: NonNullable<Catalog["terms"]> = [];
   const repos: NonNullable<Catalog["repos"]> = [];
   const repoOrigin = new Map<string, string>();
+  const deployments: NonNullable<Catalog["deployments"]> = [];
+  const deploymentOrigin = new Map<string, Map<DeploymentBasis, string>>(); // id -> basis -> source path
   const externals = new Map<string, External>();
   const externalOrigin = new Map<string, string>();
   const seen = new Map<string, string>(); // flow/adr/store/module/term id -> source path
 
   const stamps: SourceStamp[] = ordered.map((source) => ({
     path: source.path,
-    generatedAt: source.catalog.generatedAt ?? "",
-    commit: source.catalog.commit ?? "",
+    generatedAt: source.stamp?.generatedAt ?? source.catalog.generatedAt ?? "",
+    commit: source.stamp?.commit ?? source.catalog.commit ?? "",
   }));
 
   for (const { path, catalog } of ordered) {
@@ -242,6 +255,15 @@ export function mergeCatalogs(sources: CatalogSource[]): MergeResult {
     for (const store of catalog.stores ?? []) {
       if (claim(seen, store.id, path, conflicts, "store")) stores.push(store);
     }
+    // Two sources may speak about one Application, and are meant to: the
+    // GitOps tree says what should run, the deployer says what does, and
+    // the row a reader sees is the two laid over each other with the
+    // difference kept as drift (portolan.0013). Two rows of the SAME basis
+    // for one id is the collision - two snapshots of one server, two trees
+    // declaring one name - and is reported like any other.
+    for (const deployment of catalog.deployments ?? []) {
+      foldDeployment(deployments, deploymentOrigin, deployment, path, conflicts);
+    }
     // Claimed by id like everything else at this level, and that is exactly why
     // a module's id is its registry-global name rather than one derived from an
     // owner: the producer and each consumer describe the same module from
@@ -317,6 +339,7 @@ export function mergeCatalogs(sources: CatalogSource[]): MergeResult {
   if (modules.length > 0) merged.modules = modules;
   if (terms.length > 0) merged.terms = terms;
   if (repos.length > 0) merged.repos = repos;
+  if (deployments.length > 0) merged.deployments = deployments;
   if (externals.size > 0) merged.externals = [...externals.values()];
 
   return { catalog: merged, sources: stamps, conflicts };
@@ -492,6 +515,8 @@ function mergeService(
       ...(incoming.commands
         ? { commands: incoming.commands.map((c) => ({ ...c })) }
         : {}),
+      ...(incoming.hosts ? { hosts: [...incoming.hosts] } : {}),
+      ...(incoming.dials ? { dials: [...incoming.dials] } : {}),
     });
     origin.set(incoming.id, path);
 
@@ -585,6 +610,18 @@ function mergeService(
     existing.commands = commands;
   }
 
+  // Unioned like owners: two manifest trees naming where a service answers,
+  // or what it dials, are two deployments of it, and the page shows both.
+  for (const field of ["hosts", "dials"] as const) {
+    const theirs = incoming[field];
+    if (!theirs?.length) continue;
+    const names = existing[field] ?? [];
+    for (const name of theirs) {
+      if (!names.includes(name)) names.push(name);
+    }
+    existing[field] = names;
+  }
+
   if (incoming.channels?.length) {
     // Keyed by address, because that is the whole of a channel's identity. Two
     // documents describing one channel is not a conflict worth reporting - a
@@ -923,26 +960,84 @@ function raise<T extends { status: Status; note?: string }>(
  *
  * Only `declared` is raised. `unresolved` means the far end is not in the
  * catalog, and a trace showing the hop does not put it there.
+ *
+ * The second declaration may also say more than the first: a hop it saw
+ * that the code does not declare, carried as a step with `seen` on it and
+ * an id the code never gave, sitting where the recording put it; a lane
+ * such a hop needed, added after the declared ones; and the recordings
+ * themselves, as examples. Each is taken as it comes - a recording is the
+ * one witness for it - and nothing already declared moves.
  */
 export function overlayFlow(existing: Flow, incoming: Flow): Flow | undefined {
-  const lanes = (flow: Flow) => flow.participants.map((p) => p.id).join(" ");
-  if (lanes(existing) !== lanes(incoming)) return undefined;
+  const mine = existing.participants.map((p) => p.id);
+  const theirs = incoming.participants.map((p) => p.id);
+  if (theirs.length < mine.length || mine.some((id, i) => theirs[i] !== id))
+    return undefined;
 
   const steps = overlayNodes(existing.steps, incoming.steps);
   if (!steps) return undefined;
 
-  return { ...existing, steps };
+  const out: Flow = { ...existing, steps };
+  if (theirs.length > mine.length) {
+    out.participants = [
+      ...existing.participants,
+      ...incoming.participants.slice(mine.length),
+    ];
+  }
+  const examples = [...(existing.examples ?? [])];
+  const held = new Set(examples.map((example) => example.id));
+  for (const example of incoming.examples ?? []) {
+    if (!held.has(example.id)) {
+      held.add(example.id);
+      examples.push(example);
+    }
+  }
+  if (examples.length) out.examples = examples;
+
+  return out;
+}
+
+/**
+ * A node the second declaration added: a step seen in a recording and
+ * unknown to the code, or a frame where the recordings parted - an `alt`
+ * whose every step carries `seen` and whose every branch is counted. Its
+ * id is not one the first declaration has, which is how it is told from a
+ * declared node that moved.
+ */
+function isSeenAddition(node: FlowNode, against: FlowNode | undefined): boolean {
+  if (against !== undefined && against.id === node.id) return false;
+  if (node.type === "step") return node.seen !== undefined;
+  if (node.type !== "alt") return false;
+  let steps = 0;
+  const allSeen = (nodes: FlowNode[]): boolean =>
+    nodes.every((inner) => {
+      if (inner.type === "step") {
+        steps += 1;
+
+        return inner.seen !== undefined;
+      }
+
+      return inner.type === "alt" && inner.branches.every((b) => b.seen !== undefined && allSeen(b.steps));
+    });
+
+  return node.branches.every((b) => b.seen !== undefined && allSeen(b.steps)) && steps > 0;
 }
 
 function overlayNodes(
   existing: FlowNode[],
   incoming: FlowNode[],
 ): FlowNode[] | undefined {
-  if (existing.length !== incoming.length) return undefined;
   const out: FlowNode[] = [];
-  for (let i = 0; i < existing.length; i++) {
-    const a = existing[i]!;
-    const b = incoming[i]!;
+  let i = 0;
+  for (const b of incoming) {
+    const a = existing[i];
+    if (isSeenAddition(b, a)) {
+      out.push(b);
+
+      continue;
+    }
+    if (a === undefined) return undefined;
+    i++;
     if (a.type !== b.type || a.id !== b.id) return undefined;
     switch (a.type) {
       case "step": {
@@ -954,10 +1049,11 @@ function overlayNodes(
           (a.ref ?? "") !== (step.ref ?? "")
         )
           return undefined;
+        const seen = step.seen ? { seen: step.seen } : {};
         if (step.status === "verified" && a.status === "declared") {
-          out.push({ ...a, status: "verified", note: a.note || step.note });
+          out.push({ ...a, ...seen, status: "verified", note: a.note || step.note });
         } else {
-          out.push(a);
+          out.push({ ...a, ...seen });
         }
         break;
       }
@@ -999,6 +1095,8 @@ function overlayNodes(
     }
   }
 
+  if (i !== existing.length) return undefined;
+
   return out;
 }
 
@@ -1006,6 +1104,79 @@ function overlayNodes(
  * Records who owns an id. Returns false when somebody already did, which is
  * how a duplicate is skipped rather than appended twice.
  */
+/**
+ * Lays one deployment over what is already held for its id.
+ *
+ * A manifest row and an api row fold into one: the api row's shape - it is
+ * what runs, and carries the revision, the images and the link - with the
+ * manifest filling what the deployer did not say (a service the labels
+ * name, images the overlay pins when nothing runs yet), and the fields the
+ * two disagree on kept as the tree's word under `drift`. Whichever arrives
+ * first is held; the second folds onto it. Two rows of one basis are a
+ * collision and the first is kept, said out loud.
+ */
+function foldDeployment(
+  held: Deployment[],
+  origins: Map<string, Map<DeploymentBasis, string>>,
+  incoming: Deployment,
+  path: string,
+  conflicts: MergeConflict[],
+): void {
+  const basis = deploymentBasis(incoming);
+  const bases = origins.get(incoming.id) ?? new Map<DeploymentBasis, string>();
+  origins.set(incoming.id, bases);
+  const index = held.findIndex((d) => d.id === incoming.id);
+  if (index < 0) {
+    bases.set(basis, path);
+    held.push(incoming);
+    return;
+  }
+  const already = bases.get(basis);
+  if (already !== undefined || basis === "both") {
+    conflicts.push({
+      path,
+      where: incoming.id,
+      message: `deployment "${incoming.id}" is ${basis === "manifest" ? "declared" : "listed"} here and in ${already ?? "another source"}; the first one is used`,
+    });
+    return;
+  }
+  bases.set(basis, path);
+  const current = held[index]!;
+  const [manifest, api] = basis === "manifest" ? [incoming, current] : [current, incoming];
+  held[index] = laidOver(manifest, api);
+}
+
+/** The api row with the manifest laid under it, and their differences as drift. */
+function laidOver(manifest: Deployment, api: Deployment): Deployment {
+  const drift: DeploymentDrift = {};
+  if (manifest.project && manifest.project !== api.project) drift.project = manifest.project;
+  if (manifest.cluster && manifest.cluster !== api.cluster) drift.cluster = manifest.cluster;
+  if (manifest.namespace && manifest.namespace !== api.namespace) drift.namespace = manifest.namespace;
+  if (manifest.path && manifest.path !== api.path) drift.path = manifest.path;
+  if (manifest.targetRevision && manifest.targetRevision !== api.targetRevision) {
+    drift.targetRevision = manifest.targetRevision;
+  }
+  // The overlay pins some images; the cluster runs those and the base's.
+  // Drift is a pinned image that is not running, not a running image the
+  // overlay never mentioned.
+  const running = new Set(api.images ?? []);
+  const pinnedElsewhere = (manifest.images ?? []).filter((image) => !running.has(image));
+  if (pinnedElsewhere.length > 0 && (api.images?.length ?? 0) > 0) drift.images = pinnedElsewhere;
+
+  const folded: Deployment = {
+    ...api,
+    service: api.service ?? manifest.service,
+    tool: api.tool || manifest.tool,
+    images: api.images?.length ? api.images : manifest.images,
+    basis: "both",
+  };
+  if (folded.service === undefined) delete folded.service;
+  if (!folded.images?.length) delete folded.images;
+  if (Object.keys(drift).length > 0) folded.drift = drift;
+  else delete folded.drift;
+  return folded;
+}
+
 function claim(
   owners: Map<string, string>,
   id: string,

package/src/pages/AggregatePage.tsx

@@ -1,7 +1,7 @@
 import { useMemo } from "react";
 import { Link, useParams } from "react-router";
 import { catalog, index } from "../data";
-import { blockCounts, blockFields, enumsOf, rootEntity } from "../catalog";
+import { allRepos, blockCounts, blockFields, enumsOf, rootEntity } from "../catalog";
 import { isStatusEnum } from "../lib/shape";
 import type {
   Aggregate,
@@ -11,7 +11,7 @@ import type {
   Service,
   Enum,
 } from "../catalog";
-import { markdownOutline } from "../lib/derive";
+import { flowsRunning, markdownOutline } from "../lib/derive";
 import {
   redisKeyspacesPersisting,
   tablesPersisting,
@@ -33,6 +33,8 @@ import {
 } from "../routes";
 import { methodId } from "../lib/api";
 import { Markdown } from "../components/Markdown";
+import { SourcePreviewLink } from "../components/SourcePreview";
+import { sourceLocation, splitLine } from "../lib/source-link";
 import { Empty, PageHeader, SectionTitle } from "../components/PageHeader";
 import { Ident } from "../components/Ident";
 import { RowActions } from "../components/RowActions";
@@ -77,14 +79,14 @@ function BuildingBlocks({
       </div>
       <div className="flex flex-wrap items-center gap-x-4 gap-y-2 px-4 py-3">
         <span className="mono flex items-center gap-1.5 text-muted">
-          root
+          {aggregate.kind === "model-group" ? "aggregate boundary" : "root"}
           <KindIcon kind="entity" />
           {rootTo ? (
             <Link to={rootTo} className="text-ink hover:underline">
               {aggregate.root}
             </Link>
           ) : (
-            <span className="text-ink">{aggregate.root}</span>
+            <span className="text-ink">{aggregate.kind === "model-group" ? "not specified" : aggregate.root}</span>
           )}
         </span>
         <span aria-hidden className="h-4 w-px bg-line-strong" />
@@ -265,10 +267,12 @@ function OperationList({
   kind,
   operations,
   service,
+  aggregate,
 }: {
   kind: "command" | "query";
   operations: Operation[];
   service: Service;
+  aggregate: Aggregate;
 }) {
   // Whether this service records what exposes an operation at all. A catalog
   // written before anything read a transport layer says nothing either way,
@@ -277,10 +281,14 @@ function OperationList({
     aggregate.operations.some((operation) => operation.exposedBy?.length),
   );
   const to = servicePath(service.id);
+  const pins = allRepos(catalog);
 
   return (
     <ul className="flex flex-col gap-1">
-      {operations.map((op) => (
+      {operations.map((op) => {
+        const runs = flowsRunning(catalog, service, aggregate, op);
+        const location = op.source ? sourceLocation(op.source, service, pins) : null;
+        return (
         <li
           key={op.id}
           className={`flex items-start gap-2 border-l-2 px-2 py-1.5 bg-surface ${
@@ -290,7 +298,7 @@ function OperationList({
           <span className="mt-px shrink-0">
             <KindIcon kind={kind} />
           </span>
-          <div className="min-w-0">
+          <div className="min-w-0 flex-1">
             <span className="flex flex-wrap items-center gap-x-2">
               <Ident block value={op.id} className={op.deprecated ? "line-through" : undefined} />
               {op.deprecated ? (
@@ -298,8 +306,49 @@ function OperationList({
                   deprecated
                 </span>
               ) : null}
+              {op.source ? (
+                <SourcePreviewLink location={location} className="mono ml-auto text-muted hover:text-ink">
+                  {splitLine(op.source).path.split("/").pop()}
+                  {splitLine(op.source).line ? `:${splitLine(op.source).line}` : ""}
+                </SourcePreviewLink>
+              ) : null}
             </span>
             {op.doc ? <p className="mt-0.5 text-muted">{op.doc}</p> : null}
+            {/* What the caller hands in: the message's own shape. An empty
+                list is said out loud - a query that takes nothing is a fact
+                about the query, not a gap in the reading. */}
+            {op.fields ? (
+              op.fields.length ? (
+                <dl className="mono mt-1 grid grid-cols-[max-content_1fr] gap-x-3 gap-y-0.5 text-muted">
+                  {op.fields.map((field) => (
+                    <div key={field.name} className="contents">
+                      <dt className={field.deprecated ? "line-through" : undefined}>{field.name}</dt>
+                      <dd className="min-w-0 truncate">
+                        <span className="text-ink">{field.type}</span>
+                        {field.doc ? <span className="ml-2">{field.doc}</span> : null}
+                      </dd>
+                    </div>
+                  ))}
+                </dl>
+              ) : (
+                <p className="mono mt-1 text-muted">takes nothing</p>
+              )
+            ) : null}
+            {runs.length ? (
+              <p className="mono mt-1 flex flex-wrap items-center gap-x-2 text-muted">
+                <span>runs in</span>
+                {runs.map(({ flow, stepId }) => (
+                  <Link
+                    key={flow.slug}
+                    to={paths.flowStep(flow.slug, stepId)}
+                    className="rounded-control hover:text-ink"
+                    title={flow.name}
+                  >
+                    {flow.slug}
+                  </Link>
+                ))}
+              </p>
+            ) : null}
             {op.exposedBy?.length ? (
               <p className="mono mt-1 flex flex-wrap items-center gap-x-2 text-muted">
                 <span>exposed by</span>
@@ -328,7 +377,8 @@ function OperationList({
             ) : null}
           </div>
         </li>
-      ))}
+        );
+      })}
     </ul>
   );
 }
@@ -385,7 +435,7 @@ export function AggregatePage() {
       <PageHeader
         kind={
           <>
-            aggregate ·{" "}
+            {aggregate.kind === "model-group" ? "model group" : "aggregate"} ·{" "}
             <Link
               to={paths.service(context.id, service.slug)}
               className="rounded-control hover:text-ink hover:underline"
@@ -410,6 +460,7 @@ export function AggregatePage() {
           />
 
           <Markdown mermaid>{aggregate.readme}</Markdown>
+          {aggregate.kind === "model-group" ? <p className="mb-section text-muted">Models discovered in this application. Their relationships are extracted from the source; aggregate boundaries have not been specified.</p> : null}
 
           <div
             className="mt-section max-w-prose"
@@ -583,16 +634,16 @@ export function AggregatePage() {
                 anchor={AGGREGATE_ANCHOR.commands}
                 right={
                   <span>
-                    they change the aggregate — one row lock each
+                    {aggregate.kind === "model-group" ? "write operations discovered in this application" : "they change the aggregate — one row lock each"}
                   </span>
                 }
               >
                 Commands
               </SectionTitle>
               {commands.length === 0 ? (
-                <Empty>nothing changes this aggregate from outside</Empty>
+                <Empty>{aggregate.kind === "model-group" ? "no application commands discovered" : "nothing changes this aggregate from outside"}</Empty>
               ) : null}
-              <OperationList kind="command" operations={commands} service={service} />
+              <OperationList kind="command" operations={commands} service={service} aggregate={aggregate} />
             </div>
             <div id={AGGREGATE_ANCHOR.queries}>
               <SectionTitle
@@ -606,9 +657,9 @@ export function AggregatePage() {
                 Queries
               </SectionTitle>
               {queries.length === 0 ? (
-                <Empty>nothing reads this aggregate by name</Empty>
+                <Empty>{aggregate.kind === "model-group" ? "no application queries discovered" : "nothing reads this aggregate by name"}</Empty>
               ) : null}
-              <OperationList kind="query" operations={queries} service={service} />
+              <OperationList kind="query" operations={queries} service={service} aggregate={aggregate} />
             </div>
           </div>
 
@@ -750,7 +801,7 @@ export function AggregatePage() {
           />
         </div>
 
-        <Toc items={toc} label="Sections of this aggregate" title="Outline" />
+        <Toc items={toc} label={aggregate.kind === "model-group" ? "Sections of this model group" : "Sections of this aggregate"} title="Outline" />
       </div>
     </div>
   );

package/src/pages/ContextMap.tsx

@@ -17,6 +17,8 @@ import { Link, useSearchParams } from "react-router";
 import { ArrowRight, ArrowLeftRight, Boxes, Minus } from "lucide-react";
 import { catalog } from "../data";
 import { plural } from "../lib/format";
+import { narrowToEnvironments } from "../lib/environments";
+import { environmentsOf } from "../likec4/ids";
 import { PATTERN_LABEL, PATTERN_MEANING, contextMap } from "../lib/context-map";
 import type {
   ContextDependency,
@@ -439,7 +441,22 @@ export function ContextMap() {
   useDocumentTitle("Context map");
   const [search, setSearch] = useSearchParams();
   const [tour, setTour] = useState(() => search.get("tour") === "1");
-  const relations = useMemo(() => contextMap(catalog), []);
+  // The map of one environment is the same map over the services deployed
+  // there: a pair joined only through a service that is not in staging is
+  // not joined in staging. Empty means the whole estate, as every filter here.
+  const environmentChips = useMemo(() => environmentsOf(catalog), []);
+  const [environments, setEnvironments] = useState<Set<string>>(new Set());
+  const narrowed = useMemo(
+    () => narrowToEnvironments(catalog, environments),
+    [environments],
+  );
+  const relations = useMemo(() => contextMap(narrowed), [narrowed]);
+  const toggleEnvironment = (env: string) =>
+    setEnvironments((prev) => {
+      const next = new Set(prev);
+      if (!next.delete(env)) next.add(env);
+      return next;
+    });
   const joined = relations.filter(
     (r) => r.dependencies.length > 0 || r.shared.length > 0,
   );
@@ -457,9 +474,34 @@ export function ContextMap() {
       <div className="flex shrink-0 flex-wrap items-center gap-x-3 gap-y-2 border-b px-gutter py-3 border-line">
         <h1 className="text-lg font-semibold">Context map</h1>
         <span className="mono text-muted">
-          {catalog.contexts.length} {plural(catalog.contexts.length, "domain")} ·{" "}
+          {narrowed.contexts.length} {plural(narrowed.contexts.length, "domain")} ·{" "}
           {wired} of {relations.length} {plural(relations.length, "pair")} joined
         </span>
+        {environmentChips.length > 0 ? (
+          <div className="seg" role="group" aria-label="Filter by environment">
+            {environmentChips.map((env) => {
+              const on = environments.has(env);
+              return (
+                <button
+                  key={env}
+                  type="button"
+                  onClick={() => toggleEnvironment(env)}
+                  aria-pressed={on}
+                  title={`only the services the deployer places in ${env}`}
+                  className="flex items-center gap-1.5"
+                  style={{
+                    color: on ? "var(--accent)" : "var(--fg-muted)",
+                    background: on
+                      ? "color-mix(in srgb, var(--accent) 12%, transparent)"
+                      : undefined,
+                  }}
+                >
+                  {env}
+                </button>
+              );
+            })}
+          </div>
+        ) : null}
 
         {/* Two legends, and they answer different questions: what the arrow
             means, and how far a word on a chip can be trusted. */}
@@ -505,7 +547,7 @@ export function ContextMap() {
             </SectionTitle>
             <div className="h-[340px] overflow-hidden rounded-card border border-line">
               <ContextMapPane
-                catalog={catalog}
+                catalog={narrowed}
                 relations={relations}
                 zoomOnScroll={false}
               />