@shortlink-org/portolan 0.2.3 → 0.3.0

package/src/catalog-model.ts

@@ -297,7 +297,11 @@ export interface RpcMethod {
 }
 
 export interface HttpRoute {
-  /** Upper case: `POST`. */
+  /**
+   * Upper case: `POST`. Empty when a framework extractor proved the mount but
+   * no declaration proved the verb; such a route is never matched against an
+   * outbound call, and renderers show the path alone.
+   */
   method: string;
   /** As templated in the document: `/v1/users/{id}`. */
   path: string;
@@ -361,7 +365,32 @@ export interface EdgeVia {
   flow: string; // Flow.slug
   step: string; // Step.id
 }
+/** Source facts remain separate from the merge's choice of provider. */
+export interface HTTPDestination {
+  callSite: string;
+  endpointExpression: string;
+  method: string;
+  localPath?: string;
+  baseURL?: HTTPBaseURL;
+  serviceDiscoveryAlias?: string;
+  fullPath?: string;
+  join?: { expression: string; source: string };
+  /** Runtime URL modifiers after the proven join; not evaluated statically. */
+  transforms?: { expression: string; source: string }[];
+  resolution?: { basis: "full-path" | "exact-route" | "unique-suffix"; provider: string; route: string };
+}
+export interface HTTPBaseURL {
+  expression: string;
+  configField?: string;
+  environmentVariable?: string;
+  value?: string;
+  kind: "literal" | "config-default" | "symbolic";
+  source: string;
+  optionSource?: string;
+}
 export interface RpcCall {
+  evidence?: RelationEvidence[];
+  destination?: HTTPDestination;
   id: string; // "<proto.package.Service>/<Method>"
   peer: string; // service id if resolved, else raw name
   status: Status;
@@ -447,7 +476,9 @@ export interface Aggregate {
   slug: string;
   name: string;
   readme: string;
-  /** Name of the entity that is the aggregate root; must be one of `entities`. */
+  /** A source grouping has no confirmed aggregate boundary. Omitted for aggregates. */
+  kind?: "model-group";
+  /** Name of the root entity; empty only for a model-group. */
   root: string;
   entities: Entity[];
   valueObjects: ValueObject[];
@@ -627,6 +658,10 @@ export interface ChannelMessage {
   title?: string;
   doc?: string;
   direction: ChannelDirection;
+  /** Normalized payload serialization, such as `msgpack`. */
+  encoding?: string;
+  /** Exact media type declared by the source contract. */
+  contentType?: string;
 }
 export interface EventConsumer {
   service: string;
@@ -730,7 +765,7 @@ export interface RedisKeyspace {
   value?: string;
   source?: string;
   /** Aggregate or block whose value this key family holds, when provable. */
-  persists?: { aggregate?: string; block?: string };
+  persists?: { aggregate?: string; block?: string; evidence?: RelationEvidence[] };
   /** Individual client calls, before they are folded into `operations`. */
   accesses?: RedisAccess[];
 }
@@ -763,14 +798,32 @@ export const TABLE_ROLES: readonly TableRole[] = [
 ] as const;
 
 export interface Table {
+  evidence?: RelationEvidence[];
   id: string; // "<store id>.<table>"
   name: string;
   doc?: string;
   columns: Column[];
   indexes?: TableIndex[];
   /** The domain object this table holds: an aggregate id, and optionally a block id. */
-  persists?: { aggregate?: string; block?: string };
+  persists?: { aggregate?: string; block?: string; evidence?: RelationEvidence[] };
   role?: TableRole;
+  /** Source-backed repository methods that read or write this table. */
+  accesses?: TableAccess[];
+}
+
+export type TableOperation = "read" | "write" | "delete";
+
+export const TABLE_OPERATIONS: readonly TableOperation[] = [
+  "read",
+  "write",
+  "delete",
+] as const;
+
+export interface TableAccess {
+  operation: TableOperation;
+  /** Enclosing adapter method, for example `Postgres.Save`. */
+  method?: string;
+  source?: string;
 }
 
 export interface TableIndex {
@@ -832,7 +885,7 @@ export interface View {
   /** The SELECT, as the migration declares it. Shown, never parsed. */
   definition?: string;
   /** The domain object this view presents, when it presents exactly one. */
-  persists?: { aggregate?: string; block?: string };
+  persists?: { aggregate?: string; block?: string; evidence?: RelationEvidence[] };
   /** Migration or model file, as a reader would open it. */
   source?: string;
 }
@@ -887,13 +940,24 @@ export interface Participant {
   label?: string;
 }
 export type FlowNode = Step | Parallel | Alt | Loop;
+/** Source facts used to derive a relationship; not a runtime trace. */
+export interface RelationEvidence {
+  kind: "call-site" | "function" | "binding" | "contract" | "resolution" | "unresolved";
+  rule: string;
+  source?: string;
+  symbol?: string;
+  candidates?: string[];
+}
+
 export interface Step {
+  evidence?: RelationEvidence[];
+  destination?: HTTPDestination;
   type: "step";
   id: string;
   from: string;
   to: string; // participant ids; from === to is a self-message
   kind: "rpc" | "event" | "call" | "response";
-  ref?: string; // Event.id or RpcCall.id - resolvable, or status must be unresolved
+  ref?: string; // Event.id, RpcCall.id or provided RPC method id; otherwise unresolved
   label?: string;
   status: Status;
   note?: string;

package/src/catalog-stores.test.ts

@@ -45,6 +45,23 @@ describe("store validation", () => {
     expect(() => validateCatalog(clone())).not.toThrow();
   });
 
+  it("accepts source-backed table readers and writers", () => {
+    const good = clone();
+    omsStore(good).tables[0]!.accesses = [
+      { operation: "read", method: "Postgres.ByID", source: "postgres.go:40" },
+      { operation: "write", method: "Postgres.Save", source: "postgres.go:20" },
+    ];
+    expect(() => validateCatalog(good)).not.toThrow();
+  });
+
+  it("rejects an unknown table access operation", () => {
+    const bad = clone();
+    omsStore(bad).tables[0]!.accesses = [
+      { operation: "merge" as "read", method: "Postgres.Save" },
+    ];
+    expect(failureOf(bad).message).toContain("access operation");
+  });
+
   it("rejects a foreign key into a table nobody declared", () => {
     const bad = clone();
     const table = omsStore(bad).tables.find((t) => t.name === "order_items");

package/src/catalog-validation.ts

@@ -16,6 +16,7 @@ import {
   REDIS_OPERATIONS,
   STORE_KINDS,
   STREAMING,
+  TABLE_OPERATIONS,
   TABLE_ROLES,
   aggregateBlocks,
   allAggregates,
@@ -124,6 +125,18 @@ function validateChannels(service: Service): void {
           `service ${service.id} / channel ${channel.address}`,
         );
       }
+      if (message.encoding !== undefined && (typeof message.encoding !== "string" || message.encoding === "")) {
+        fail(
+          `message "${message.name}" on channel "${channel.address}" has an empty encoding`,
+          `service ${service.id} / channel ${channel.address}`,
+        );
+      }
+      if (message.contentType !== undefined && (typeof message.contentType !== "string" || message.contentType === "")) {
+        fail(
+          `message "${message.name}" on channel "${channel.address}" has an empty content type`,
+          `service ${service.id} / channel ${channel.address}`,
+        );
+      }
       const key = `${message.direction} ${message.name}`;
       if (seen.has(key)) {
         fail(
@@ -142,6 +155,15 @@ export function validateCatalog(catalog: Catalog): Catalog {
 
   const eventIds = new Set<string>();
   const rpcIds = new Set<string>();
+  const providedRpcRefs = new Set(
+    allExternals(catalog).flatMap((external) =>
+      external.provides.flatMap((provided) =>
+        provided.methods.map(
+          (method) => `${external.id}|${provided.id}/${method.name}`,
+        ),
+      ),
+    ),
+  );
   const storeIds = new Set(allStores(catalog).map((store) => store.id));
 
   assertUniqueSlugs(
@@ -232,6 +254,13 @@ export function validateCatalog(catalog: Catalog): Catalog {
         technologies.add(technology);
       }
       for (const call of service.consumes) rpcIds.add(call.id);
+      for (const provided of service.provides) {
+        for (const method of provided.methods) {
+          providedRpcRefs.add(
+            `${service.id}|${provided.id}/${method.name}`,
+          );
+        }
+      }
       for (const provided of [
         ...service.provides,
         ...(service.copies ?? []),
@@ -589,10 +618,14 @@ export function validateCatalog(catalog: Catalog): Catalog {
         );
       }
       if (step.ref !== undefined && step.status !== "unresolved") {
-        const resolves = eventIds.has(step.ref) || rpcIds.has(step.ref);
+        const resolves =
+          eventIds.has(step.ref) ||
+          rpcIds.has(step.ref) ||
+          (step.kind === "rpc" &&
+            providedRpcRefs.has(`${step.to}|${step.ref}`));
         if (!resolves) {
           fail(
-            `flow "${flow.slug}" step "${step.id}": ref "${step.ref}" resolves to neither an Event nor an RpcCall, and status is "${step.status}" rather than "unresolved"`,
+            `flow "${flow.slug}" step "${step.id}": ref "${step.ref}" resolves to neither an Event, an RpcCall nor a method provided by "${step.to}", and status is "${step.status}" rather than "unresolved"`,
             `flow ${flow.id} / step ${step.id}`,
           );
         }
@@ -990,6 +1023,14 @@ function validateStores(catalog: Catalog): void {
           where,
         );
       }
+      for (const access of table.accesses ?? []) {
+        if (!TABLE_OPERATIONS.includes(access.operation)) {
+          fail(
+            `table "${table.id}" has access operation "${access.operation}"; expected one of ${TABLE_OPERATIONS.join(", ")}`,
+            where,
+          );
+        }
+      }
 
       const own = columnsOfTable.get(table.id) ?? new Set<string>();
       if (own.size !== table.columns.length) {
@@ -1311,6 +1352,15 @@ function validateBlocks(catalog: Catalog, aggregate: Aggregate): void {
 
   validateEnums(aggregate);
 
+  if (aggregate.kind !== undefined && aggregate.kind !== "model-group") {
+    fail(`aggregate "${aggregate.id}" has an unknown kind`, `aggregate ${aggregate.id}`);
+  }
+  if (aggregate.kind === "model-group") {
+    if (aggregate.root !== "" || aggregate.lifecycle) {
+      fail(`model group "${aggregate.id}" cannot declare an aggregate root or lifecycle`, `aggregate ${aggregate.id}`);
+    }
+    return;
+  }
   if (!aggregate.root) {
     fail(
       `aggregate "${aggregate.id}" names no root entity`,

package/src/catalog.test.ts

@@ -105,7 +105,7 @@ describe("validateCatalog", () => {
     if (!step) throw new Error("fixture has no steps");
     step.ref = "shop.oms.order.NoSuchEvent";
     expect(() => validateCatalog(bad)).toThrowError(
-      /resolves to neither an Event nor an RpcCall/,
+      /resolves to neither an Event, an RpcCall nor a method/,
     );
     step.status = "unresolved";
     expect(() => validateCatalog(bad)).not.toThrow();
@@ -1077,7 +1077,10 @@ describe("validateCatalog: channels", () => {
   }
 
   it("accepts a service that declares what it says on the bus", () => {
-    expect(() => validateCatalog(speaking())).not.toThrow();
+    const good = speaking();
+    good.contexts[0]!.services[0]!.channels![0]!.messages[0]!.encoding = "msgpack";
+    good.contexts[0]!.services[0]!.channels![0]!.messages[0]!.contentType = "application/msgpack";
+    expect(() => validateCatalog(good)).not.toThrow();
   });
 
   // A service with no document is the normal case, and it is not a service
@@ -1130,6 +1133,14 @@ describe("validateCatalog: channels", () => {
 
     expect(() => validateCatalog(bad)).toThrow(/neither send nor receive/);
   });
+
+  it("rejects an explicitly empty message encoding", () => {
+    const bad = speaking();
+    const message = bad.contexts[0]!.services[0]!.channels![0]!.messages[0]!;
+    message.encoding = "";
+
+    expect(() => validateCatalog(bad)).toThrow(/empty encoding/);
+  });
 });
 
 // A system outside the estate with a contract sits at the root beside the

package/src/chat/Starter.tsx

@@ -6,7 +6,7 @@
 
 import { KindIcon } from "../components/kind";
 import type { Kind } from "../lib/kinds";
-import { activeCatalogProfile, catalog } from "../data";
+import { activeCatalogDocs, catalog } from "../data";
 import type { ChatPageContext } from "./page-context";
 import { contextQuestions } from "./page-context";
 
@@ -36,8 +36,6 @@ function examples(): Example[] {
   return out;
 }
 
-const base = import.meta.env.BASE_URL;
-
 export function Starter({
   onAsk,
   page,
@@ -51,10 +49,6 @@ export function Starter({
         question,
       }))
     : examples();
-  const profileSuffix =
-    activeCatalogProfile.id === "portolan" ? "" : `${activeCatalogProfile.id}/`;
-  const docsRoot = `${base}docs/${profileSuffix}`;
-  const indexHref = profileSuffix ? `${docsRoot}llms.txt` : `${base}llms.txt`;
 
   return (
     <div className="pt-1">
@@ -79,10 +73,10 @@ export function Starter({
               <div className="mono truncate text-muted" title={page.id}>{page.id}</div>
             </div>
           </div>
-          <div className="mono mt-2.5 flex flex-wrap items-center gap-x-2 gap-y-1 border-t border-line pt-2 text-muted">
+          {activeCatalogDocs ? <div className="mono mt-2.5 flex flex-wrap items-center gap-x-2 gap-y-1 border-t border-line pt-2 text-muted">
             <span className="text-faint">model context</span>
             <a
-              href={indexHref}
+              href={activeCatalogDocs.index}
               target="_blank"
               rel="noreferrer"
               className="rounded-control text-accent hover:underline"
@@ -91,7 +85,7 @@ export function Starter({
             </a>
             {page.docPath ? (
               <a
-                href={`${docsRoot}${page.docPath}`}
+                href={`${activeCatalogDocs.pages}${page.docPath}`}
                 target="_blank"
                 rel="noreferrer"
                 className="max-w-full truncate rounded-control text-accent hover:underline"
@@ -100,7 +94,7 @@ export function Starter({
                 current catalog page
               </a>
             ) : null}
-          </div>
+          </div> : null}
         </div>
       ) : null}
       <div className="label mt-5 mb-1">try one</div>

package/src/chat/tools.test.ts

@@ -0,0 +1,27 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { catalogDocs } from "../catalog-docs";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.doUnmock("../data");
+  vi.resetModules();
+});
+
+it.each([
+  { id: "default", generate: [{ plugin: "markdown", out: "docs" }], index: "/portolan/llms.txt", pages: "/portolan/docs/" },
+  { id: "example", generate: [
+    { plugin: "markdown", catalog: "portolan", out: "docs" },
+    { plugin: "markdown", catalog: "example", out: "docs/example" },
+  ], index: "/portolan/docs/example/llms.txt", pages: "/portolan/docs/example/" },
+])("loads the index and catalog pages for $id", async ({ id, generate, index, pages }) => {
+  vi.doMock("../data", () => ({ activeCatalogDocs: catalogDocs({ generate }, id, "/portolan/") }));
+  const fetcher = vi.fn().mockResolvedValue(new Response("# Catalog documentation"));
+  vi.stubGlobal("fetch", fetcher);
+  const tools = await import("./tools");
+
+  expect(await tools.loadIndex()).toBe("# Catalog documentation");
+  expect(fetcher).toHaveBeenLastCalledWith(index);
+  fetcher.mockResolvedValue(new Response("# Auth service"));
+  expect(await tools.readPage("docs/auth/README.md")).toBe("# Auth service");
+  expect(fetcher).toHaveBeenLastCalledWith(`${pages}auth/README.md`);
+});

package/src/chat/tools.ts

@@ -6,19 +6,14 @@
 
 import { jsonSchema, tool } from "ai";
 import { clipPage, pagePath, TOOL_SPECS } from "./prompt";
-import { activeCatalogProfile } from "../data";
-
-const base = import.meta.env.BASE_URL;
-const profileSuffix =
-  activeCatalogProfile.id === "portolan" ? "" : `${activeCatalogProfile.id}/`;
-const docsBase = `${base}docs/${profileSuffix}`;
-const indexUrl = profileSuffix ? `${docsBase}llms.txt` : `${base}llms.txt`;
+import { activeCatalogDocs } from "../data";
 
 /** One page of the generated docs, as the model gets it. */
 export async function readPage(raw: unknown): Promise<string> {
   const path = pagePath(raw);
   if (!path) return "That is not a page of the catalog. Use a path from the index.";
-  const response = await fetch(`${docsBase}${path.slice("docs/".length)}`);
+  if (!activeCatalogDocs) return "No documentation is configured for this catalog.";
+  const response = await fetch(`${activeCatalogDocs.pages}${path.slice("docs/".length)}`);
   if (!response.ok) return `No page at ${path}. Use a path from the index.`;
   return clipPage(await response.text());
 }
@@ -26,7 +21,8 @@ export async function readPage(raw: unknown): Promise<string> {
 /** llms.txt, once per session. */
 let indexPromise: Promise<string> | null = null;
 export function loadIndex(): Promise<string> {
-  indexPromise ??= fetch(indexUrl).then((response) => {
+  if (!activeCatalogDocs) return Promise.reject(new Error("No documentation is configured for this catalog."));
+  indexPromise ??= fetch(activeCatalogDocs.index).then((response) => {
     if (!response.ok) {
       indexPromise = null;
       throw new Error("the catalog index (llms.txt) could not be read");

package/src/components/CatalogStamp.tsx

@@ -6,23 +6,25 @@ import { absoluteTime, plural, relativeTime } from "../lib/format";
 /**
  * Where the catalog on this page came from, and when.
  *
- * The header says one date and one commit, and both are summaries of a corpus:
- * the date is the OLDEST of the sources, because a merged catalog is exactly
- * as fresh as its stalest part, and the commit is a count whenever the sources
- * do not agree on one. A summary of many numbers is the right thing to put in
- * a header and the wrong thing to leave a reader with - "6 sources · 15 hours
+ * A source is dated by the commit that last changed it, read off the
+ * checkout's history rather than out of the file (portolan.0010). The header
+ * says one date and one commit, and both are summaries of a corpus: the date
+ * is the OLDEST of the sources, because a merged catalog is exactly as fresh
+ * as its stalest part, and the commit is a count whenever the sources do not
+ * agree on one. A summary of many numbers is the right thing to put in a
+ * header and the wrong thing to leave a reader with - "6 sources · 15 hours
  * ago" answers "is this current" and refuses "which part is not", which is the
  * question anyone who did not like the first answer asks next.
  *
  * So the stamp opens. Behind it is one row per commit, newest first, and the
  * row the header is quoting says so. Rows are per COMMIT and not per file
- * because twenty-eight fragments written by one commit are one source of
+ * because twenty-eight fragments changed by one commit are one source of
  * facts, and it is the same count the header prints.
  */
 export function CatalogStamp() {
   const groups = byCommit(catalogSources);
   const authored = catalogSources.filter((source) => !source.commit);
-  const summary = `catalog generated ${absoluteTime(catalog.generatedAt)} from commit ${catalog.commit}`;
+  const summary = `catalog last changed ${absoluteTime(catalog.generatedAt)}, ${catalog.commit}`;
 
   return (
     <Popover className="ml-auto">
@@ -43,7 +45,7 @@ export function CatalogStamp() {
       >
         <div className="label mb-1.5 px-1">
           {groups.length} {plural(groups.length, "source")}, by the commit each
-          was generated from
+          last changed in
         </div>
         <dl className="mono grid grid-cols-[auto_1fr_auto] items-baseline gap-x-3 gap-y-1 px-1">
           {groups.map((group, i) => (

package/src/components/ChannelRows.messagepack.test.tsx

@@ -0,0 +1,28 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { MemoryRouter } from "react-router";
+import { describe, expect, it } from "vitest";
+import type { Channel } from "../catalog";
+import { ChannelRows } from "./ChannelRows";
+
+describe("ChannelRows MessagePack presentation", () => {
+  it("shows a machine-readable encoding with its declared content type", () => {
+    const channel: Channel = {
+      address: "inventory.snapshots",
+      kind: "message",
+      messages: [{
+        name: "inventory.Snapshot",
+        direction: "send",
+        encoding: "msgpack",
+        contentType: "application/msgpack",
+      }],
+    };
+    const markup = renderToStaticMarkup(
+      <MemoryRouter>
+        <ChannelRows channels={[channel]} service="shop.inventory" />
+      </MemoryRouter>,
+    );
+
+    expect(markup).toContain('title="application/msgpack"');
+    expect(markup).toContain(">msgpack</span>");
+  });
+});

package/src/components/ChannelRows.test.tsx

@@ -0,0 +1,54 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { MemoryRouter } from "react-router";
+import { describe, expect, it } from "vitest";
+import type { Channel } from "../catalog";
+import { ChannelRowsContent } from "./ChannelRows";
+
+const kafka: Channel = {
+  address: "orders/created",
+  kind: "message",
+  title: "Kafka · orders/created",
+  messages: [],
+};
+
+const nats: Channel = {
+  address: "orders.created",
+  kind: "message",
+  title: "JetStream subject",
+  messages: [],
+};
+
+describe("ChannelRows Kafka UI integration", () => {
+  it("links only Kafka cards to their exact topic when configured", () => {
+    const markup = renderToStaticMarkup(
+      <MemoryRouter>
+        <ChannelRowsContent
+          channels={[kafka, nats]}
+          service="shop.orders"
+          kafkaUi="https://ops.example/ui/clusters/prod"
+        />
+      </MemoryRouter>,
+    );
+
+    expect(markup).toContain("view in Kafka UI");
+    expect(markup).toContain(
+      'href="https://ops.example/ui/clusters/prod/all-topics/orders%2Fcreated"',
+    );
+    expect(markup.match(/view in Kafka UI/g)).toHaveLength(1);
+  });
+
+  it("does not offer an operational link before Kafka UI is configured", () => {
+    const markup = renderToStaticMarkup(
+      <MemoryRouter>
+        <ChannelRowsContent
+          channels={[kafka]}
+          service="shop.orders"
+          kafkaUi=""
+        />
+      </MemoryRouter>,
+    );
+
+    expect(markup).not.toContain("view in Kafka UI");
+  });
+
+});

package/src/components/ChannelRows.tsx

@@ -13,13 +13,22 @@
 // Problems page says which; a row that quietly dropped it would be the site
 // hiding the interesting case.
 
+import { ExternalLink } from "lucide-react";
 import { Link } from "react-router";
 import type { Channel, ChannelMessage } from "../catalog";
-import { index } from "../data";
+import { catalog, index } from "../data";
+import {
+  isKafkaChannel,
+  kafkaHandoffChannels,
+  kafkaUiTopicUrl,
+  useKafkaUi,
+} from "../lib/kafka-ui";
 import { eventPath } from "../routes";
 import { Ident } from "./Ident";
 import { RowActions } from "./RowActions";
 
+const KAFKA_HANDOFF_CHANNELS = kafkaHandoffChannels(catalog);
+
 /** The event that goes out under a wire name, when the catalog knows one. */
 function publisherOf(name: string) {
   const event = index.eventByWireName.get(name);
@@ -75,6 +84,11 @@ function MessageRow({
               {elsewhere}
             </span>
           ) : null}
+          {message.encoding || message.contentType ? (
+            <span className="chip mono" title={message.contentType || "payload encoding"}>
+              {message.encoding || message.contentType}
+            </span>
+          ) : null}
         </div>
         {message.title || message.doc ? (
           <p className="mt-0.5 text-muted">{message.doc || message.title}</p>
@@ -91,20 +105,53 @@ export function ChannelRows({
 }: {
   channels: Channel[];
   service: string;
+}) {
+  const kafkaUi = useKafkaUi((state) => state.url);
+  return (
+    <ChannelRowsContent
+      channels={channels}
+      service={service}
+      kafkaUi={kafkaUi}
+    />
+  );
+}
+
+/** The presentational half is exported so the generated links can be rendered in isolation. */
+export function ChannelRowsContent({
+  channels,
+  service,
+  kafkaUi,
+}: {
+  channels: Channel[];
+  service: string;
+  kafkaUi: string;
 }) {
   return (
     <div className="flex flex-col gap-section" data-nav-list>
       {channels.map((channel) => (
         <div key={channel.address} className="rounded-card border border-line">
-          <div className="flex flex-wrap items-baseline gap-x-2 border-b border-line px-3 py-2">
-            <Ident value={channel.address} />
-            {channel.kind === "job" ? (
-              <span className="chip">work queue</span>
-            ) : channel.kind === "message" ? (
-              <span className="chip">message stream</span>
-            ) : null}
-            {channel.title ? (
-              <span className="text-muted">{channel.title}</span>
+          <div className="flex flex-wrap items-center gap-x-3 gap-y-2 border-b border-line px-3 py-2">
+            <div className="flex min-w-0 flex-1 flex-wrap items-baseline gap-x-2">
+              <Ident value={channel.address} />
+              {channel.kind === "job" ? (
+                <span className="chip">work queue</span>
+              ) : channel.kind === "message" ? (
+                <span className="chip">message stream</span>
+              ) : null}
+              {channel.title ? (
+                <span className="text-muted">{channel.title}</span>
+              ) : null}
+            </div>
+            {kafkaUi && isKafkaChannel(channel, KAFKA_HANDOFF_CHANNELS) ? (
+              <a
+                href={kafkaUiTopicUrl(kafkaUi, channel.address) ?? kafkaUi}
+                target="_blank"
+                rel="noreferrer"
+                className="mono inline-flex shrink-0 items-center gap-1 whitespace-nowrap rounded-control text-accent hover:underline"
+                title={`Open ${channel.address} in Kafka UI`}
+              >
+                view in Kafka UI <ExternalLink size={12} aria-hidden />
+              </a>
             ) : null}
           </div>
           {channel.doc ? (