@shortlink-org/portolan 0.2.4 → 0.3.0

package/src/catalog-docs.ts

@@ -0,0 +1,35 @@
+export interface DocsManifest {
+  generate?: { plugin: string; catalog?: string; out: string }[];
+}
+
+export interface CatalogDocs {
+  pages: string;
+  index: string;
+  full: string;
+}
+
+/** Match site-docs.mjs: the first markdown output is mounted at docs/.
+ * Other catalogs are available when generated inside that output directory.
+ */
+export function catalogDocs(
+  manifest: DocsManifest,
+  profileId: string,
+  base: string,
+): CatalogDocs | null {
+  const steps = manifest.generate?.filter((step) => step.plugin === "markdown") ?? [];
+  const root = steps[0];
+  const selected = steps.find((step) => step.catalog === profileId)
+    ?? steps.find((step) => !step.catalog);
+  if (!root || !selected) return null;
+
+  const directory = (out: string) => new URL(`${out.replace(/\/$/, "")}/`, "https://workspace.invalid/").pathname;
+  const rootPath = directory(root.out);
+  const selectedPath = directory(selected.out);
+  if (!selectedPath.startsWith(rootPath)) return null;
+
+  const prefix = base.endsWith("/") ? base : `${base}/`;
+  const suffix = selectedPath.slice(rootPath.length);
+  const pages = `${prefix}docs/${suffix}`;
+  const indexRoot = suffix ? pages : prefix;
+  return { pages, index: `${indexRoot}llms.txt`, full: `${indexRoot}llms-full.txt` };
+}

package/src/catalog-error.test.ts

@@ -21,6 +21,21 @@ function failureOf(catalog: Catalog): CatalogError {
 }
 
 describe("CatalogError.path", () => {
+  it("allows rootless source groups while preserving aggregate root validation", () => {
+    const data = clone();
+    const aggregate = data.contexts[0]!.services[0]!.aggregates[0]!;
+    aggregate.root = "";
+    delete aggregate.lifecycle;
+    expect(() => validateCatalog(data)).toThrow(/names no root/);
+    aggregate.kind = "model-group";
+    expect(() => validateCatalog(data)).not.toThrow();
+    aggregate.root = aggregate.entities[0]!.name;
+    expect(() => validateCatalog(data)).toThrow(/cannot declare an aggregate root/);
+    aggregate.root = "";
+    aggregate.lifecycle = { states: ["Active"], transitions: [] };
+    expect(() => validateCatalog(data)).toThrow(/cannot declare an aggregate root or lifecycle/);
+  });
+
   it("names the flow and the step for a step that points at a missing lane", () => {
     const bad = clone();
     const flow = bad.flows[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[];
@@ -734,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[];
 }
@@ -767,13 +798,14 @@ 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[];
@@ -853,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;
 }
@@ -908,7 +940,18 @@ 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;

package/src/catalog-validation.ts

@@ -1352,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/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/HTTPDestinationEvidence.test.tsx

@@ -0,0 +1,23 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { expect, it } from "vitest";
+import { HTTPDestinationEvidence } from "./HTTPDestinationEvidence";
+
+it("shows the join and the config default behind a resolved destination", () => {
+  const html = renderToStaticMarkup(<HTTPDestinationEvidence destination={{
+    callSite: "client.go:10", endpointExpression: "c.baseURL + path", method: "POST",
+    localPath: "/get-admin-settings", fullPath: "/settings/get-admin-settings",
+    baseURL: { expression: "cfg.SettingAddr", configField: "Config.SettingAddr", environmentVariable: "SETTINGS_ADDR", kind: "config-default", value: "http://localhost:8000/settings", source: "config.go:84", optionSource: "modules_tree.go:212" },
+    join: { expression: "c.baseURL + path", source: "client.go:10" },
+    resolution: { basis: "full-path", provider: "avia.aviaadmin", route: "/settings/get-admin-settings" },
+  }} />);
+  for (const value of ["Recovered full path", "Config default (runtime may override)", "SETTINGS_ADDR", "modules_tree.go:212", "Config.SettingAddr", "/settings/get-admin-settings", "avia.aviaadmin"]) expect(html).toContain(value);
+  expect(html).not.toContain("heuristic");
+});
+
+it("labels suffix resolution as a heuristic", () => {
+  const html = renderToStaticMarkup(<HTTPDestinationEvidence destination={{
+    callSite: "client.go:10", endpointExpression: "/settings", method: "POST",
+    resolution: { basis: "unique-suffix", provider: "admin", route: "/admin/settings" },
+  }} />);
+  expect(html).toContain("Unique route suffix (heuristic)");
+});

package/src/components/HTTPDestinationEvidence.tsx

@@ -0,0 +1,31 @@
+import type { HTTPDestination } from "../catalog";
+
+/** Display the facts for this invocation, including the limits of defaults. */
+export function HTTPDestinationEvidence({ destination: d }: { destination: HTTPDestination }) {
+  const basis = d.resolution?.basis;
+  const rows = [
+    ["Linked by", basis === "full-path" ? "Recovered full path" : basis === "exact-route" ? "Exact route" : basis === "unique-suffix" ? "Unique route suffix (heuristic)" : "Unresolved"],
+    ["Call site", d.callSite],
+    ["Endpoint expression", d.endpointExpression],
+    ["Local path", d.localPath],
+    ["Base URL expression", d.baseURL?.expression],
+    ["Config field", d.baseURL?.configField],
+    ["Environment variable", d.baseURL?.environmentVariable],
+    [d.baseURL?.kind === "config-default" ? "Config default (runtime may override)" : "Base URL", d.baseURL?.value],
+    ["Config source", d.baseURL?.source],
+    ["Option call site", d.baseURL?.optionSource],
+    ["Service discovery alias", d.serviceDiscoveryAlias],
+    ["Join expression", d.join?.expression],
+    ["Join source", d.join?.source],
+    ["Full path", d.fullPath],
+    ...(d.transforms ?? []).map((transform) => ["Runtime URL modifier (not evaluated)", `${transform.expression} · ${transform.source}`]),
+    ["Provider", d.resolution?.provider],
+    ["Provider route", d.resolution?.route],
+  ].filter(([, value]) => value);
+  return <section aria-label="HTTP destination evidence" className="border-t border-line px-3 py-3">
+    <h3 className="label mb-2">HTTP destination evidence</h3>
+    <dl className="grid min-w-0 grid-cols-1 gap-y-3">
+      {rows.map(([label, value], index) => <div key={`${label}-${index}`} className="min-w-0"><dt className="text-muted">{label}</dt><dd className="mono break-all text-ink">{value}</dd></div>)}
+    </dl>
+  </section>;
+}

package/src/components/Integrations.tsx

@@ -210,7 +210,7 @@ export function Integrations({ groups }: { groups: IntegrationGroup[] }) {
                         <RowActions copy={call.id} label={call.id} />
                         {method?.http ? (
                           <p className="mono w-full text-muted">
-                            {method.http.method} {method.http.path}
+                            {method.http.method ? `${method.http.method} ${method.http.path}` : method.http.path}
                           </p>
                         ) : null}
                         {call.note ? (

package/src/components/MachineDocs.tsx

@@ -1,5 +1,5 @@
 import { FileText } from "lucide-react";
-import { activeCatalogProfile } from "../data";
+import { activeCatalogDocs, activeCatalogProfile } from "../data";
 
 // The site as a language model reads it. The build (scripts/site-docs.mjs)
 // places the generated markdown under docs/ and llms.txt at the root, in the
@@ -10,11 +10,12 @@ import { activeCatalogProfile } from "../data";
 const base = import.meta.env.BASE_URL;
 
 const suffix = activeCatalogProfile.id === "portolan" ? "" : `${activeCatalogProfile.id}/`;
-const docs = `${base}docs/${suffix}`;
 const FILES = [
-  { href: suffix ? `${docs}llms.txt` : `${base}llms.txt`, label: "llms.txt", title: "An index of every page, for a model that fetches on demand" },
-  { href: suffix ? `${docs}llms-full.txt` : `${base}llms-full.txt`, label: "llms-full.txt", title: "Every page in one file, for a model with a context window" },
-  { href: docs, label: "docs/", title: "The generated markdown, page by page" },
+  ...(activeCatalogDocs ? [
+    { href: activeCatalogDocs.index, label: "llms.txt", title: "An index of every page, for a model that fetches on demand" },
+    { href: activeCatalogDocs.full, label: "llms-full.txt", title: "Every page in one file, for a model with a context window" },
+    { href: activeCatalogDocs.pages, label: "docs/", title: "The generated markdown, page by page" },
+  ] : []),
   { href: `${base}exports/mermaid/${suffix}`, label: "Mermaid", title: "Standalone sequence diagrams for every architecture flow" },
   ...(activeCatalogProfile.id === "example"
     ? [{ href: `${base}exports/backstage/catalog-info.yaml`, label: "Backstage", title: "Components, systems, APIs and resources for a Backstage catalog" }]

package/src/components/MethodRows.tsx

@@ -167,8 +167,15 @@ export function MethodRows({
                   className={method.deprecated ? "line-through" : undefined}
                 />
                 {method.http ? (
-                  <span className="chip mono" title="the route this operation answers on">
-                    {method.http.method} {method.http.path}
+                  <span
+                    className="chip mono"
+                    title={
+                      method.http.method
+                        ? "the route this operation answers on"
+                        : "the route this operation answers on; the HTTP verb is not declared in source"
+                    }
+                  >
+                    {method.http.method ? `${method.http.method} ${method.http.path}` : method.http.path}
                   </span>
                 ) : null}
                 {method.soap ? (

package/src/components/RelationEvidence.test.tsx

@@ -0,0 +1,14 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { expect, it } from "vitest";
+import { RelationEvidencePanel } from "./RelationEvidence";
+
+it("explains an ambiguous binding without choosing a candidate", () => {
+  const html = renderToStaticMarkup(<RelationEvidencePanel items={[
+    { kind: "binding", rule: "provider-signature", source: "di.go:12", symbol: "Build" },
+    { kind: "unresolved", rule: "ambiguous-binding", candidates: ["First", "Second"] },
+  ]} />);
+  for (const value of ["Why this relation exists", "inferred", "di.go:12", "Several implementations remain possible", "First", "Second"]) expect(html).toContain(value);
+});
+it("shows the absence of evidence explicitly", () => {
+  expect(renderToStaticMarkup(<RelationEvidencePanel items={[]} />)).toContain("No source evidence recorded");
+});

package/src/components/RelationEvidence.tsx

@@ -0,0 +1,53 @@
+import type { ReactNode } from "react";
+import type { RelationEvidence } from "../catalog";
+
+const labels: Record<RelationEvidence["kind"], string> = {
+  "call-site": "Call site", function: "Function", binding: "Dependency binding",
+  contract: "Contract", resolution: "Catalog resolution", unresolved: "Unresolved",
+};
+const rules: Record<string, string> = {
+  "source-expression": "Expression in source",
+  "source-function": "Enclosing source function",
+  "provider-signature": "Provider signature (inferred)",
+  "store-port-convention": "Storage field, type or package name (inferred)",
+  "domain-port-convention": "Domain port mapped to the configured store (inferred)",
+  "ambiguous-binding": "Several implementations remain possible",
+  "generated-client-method": "Method declared by generated client",
+  "http-expression": "Outbound HTTP expression",
+  "analyzed-call-path": "Static analysis path; not a runtime trace",
+  "client-contract": "Client contract",
+  "catalog-contract": "Matching interface and method",
+  "event-declaration": "Declared event",
+  "repository-sql-call": "SQL operation inside repository",
+  "full-path": "Recovered full HTTP path",
+  "exact-route": "Exact HTTP route",
+  "unique-suffix": "Unique route suffix (heuristic)",
+  "continuation-entrypoint": "Matched continuation entrypoint",
+  "response-to-request": "Response associated with request",
+  "unresolved-target": "No unique target established",
+  "sql-alter-table": "ALTER TABLE in migration",
+  "sql-view-definition": "SQL view definition",
+  "sql-create-table": "CREATE TABLE in migration",
+  "domain-root-and-repository-layout": "Domain root and repository convention (inferred)",
+  "migration-aggregate-annotation": "Explicit aggregate annotation in migration",
+};
+
+/** One explanation surface for all flow kinds and schema relationships. */
+export function RelationEvidencePanel({ items, renderSource }: {
+  items: readonly RelationEvidence[];
+  renderSource?: (source: string) => ReactNode;
+}) {
+  return <section aria-label="Why this relation exists" className="my-3 rounded-card border border-line bg-surface p-3">
+    <h3 className="label mb-2">Why this relation exists</h3>
+    {items.length === 0 ? <p className="text-muted">No source evidence recorded in this fragment.</p> :
+      <ol className="space-y-3">
+        {items.map((item, i) => <li key={`${item.kind}-${i}`} className="min-w-0 border-l-2 border-line pl-3">
+          <div className={item.kind === "unresolved" ? "text-[var(--status-unresolved)]" : "text-ink"}>{labels[item.kind]}</div>
+          <div className="text-muted">{rules[item.rule] ?? item.rule}</div>
+          {item.symbol ? <div className="mono break-all">{item.symbol}</div> : null}
+          {item.source ? <div className="mono break-all text-muted">{renderSource ? renderSource(item.source) : item.source}</div> : null}
+          {item.candidates?.length ? <div className="mt-1"><span className="text-muted">Candidates</span><ul>{item.candidates.map((candidate) => <li className="mono break-all" key={candidate}>{candidate}</li>)}</ul></div> : null}
+        </li>)}
+      </ol>}
+  </section>;
+}

package/src/data.ts

@@ -32,6 +32,11 @@ import type {
   SourceStamp,
 } from "./merge";
 import manifestJson from "../portolan.json";
+import { catalogDocs } from "./catalog-docs";
+// When each source last changed, as the checkout's history says - served by
+// scripts/provenance.mjs at build time, because a fragment carries no
+// provenance of its own (portolan.0010) and a browser cannot ask git.
+import provenance from "virtual:portolan-provenance";
 
 const manifest = manifestJson as CatalogProfileManifest & { sources: string[] };
 export const catalogProfiles: CatalogProfile[] = profilesFromManifest(manifest);
@@ -56,6 +61,8 @@ export const activeCatalogProfile = catalogProfileNamed(
   requestedProfileFromUrl(),
 );
 
+export const activeCatalogDocs = catalogDocs(manifestJson, activeCatalogProfile.id, import.meta.env.BASE_URL);
+
 /**
  * Where sources are looked for. The patterns are written out because
  * import.meta.glob resolves at build time and needs literals - and because
@@ -120,15 +127,26 @@ interface Loaded {
 
 function load(): Loaded {
   const sources: CatalogSource[] = Object.entries(modules)
-    .map(([path, catalog]) => ({
+    .map(([key, catalog]) => {
       // Vite keys a glob by its pattern-relative path; the leading ../ is an
       // artefact of this file's location, not part of where anything lives.
-      path: path.replace(/^\.\.\//, ""),
-      // A SOURCE, not a catalog: the two stamps are optional in a file, and
-      // the estate's authored facts carry neither.
-      catalog: catalog as SourceCatalog,
-    }))
-    .filter((source) => profileIncludesSource(activeCatalogProfile, source.path));
+      const imported = key.replace(/^\.\.\//, "");
+      // A SOURCE, not a catalog: a file carries no stamp of its own, and the
+      // history's travels beside it (portolan.0010).
+      const { source, ...stamp } = provenance[imported] ?? {};
+      return {
+        imported,
+        // A staged site imports a source under a flattened name; the file is
+        // still the one in the workspace, and that is the path a project's
+        // root is a prefix of and a link to the file names.
+        path: source ?? imported,
+        catalog: catalog as SourceCatalog,
+        stamp: "commit" in stamp ? stamp : undefined,
+      };
+    })
+    // The profile spells its sources the way the site imports them.
+    .filter((source) => profileIncludesSource(activeCatalogProfile, source.imported))
+    .map(({ imported: _imported, ...source }) => source);
 
   const merged = mergeCatalogs(sources);
   // Enriched before it is validated: the edges the flows imply are part of