@shortlink-org/portolan 0.1.0

package/src/testing/estate/examples__shop__cart__portolan__stores.json

@@ -0,0 +1,208 @@
+{
+  "generatedAt": "2026-09-05T01:37:11+07:00",
+  "commit": "08fcaaa",
+  "contexts": [
+    {
+      "id": "shop",
+      "slug": "shop",
+      "name": "",
+      "summary": "",
+      "services": [
+        {
+          "id": "shop.cart",
+          "slug": "cart",
+          "name": "",
+          "repo": "",
+          "path": "",
+          "readme": "",
+          "provides": [],
+          "consumes": [],
+          "aggregates": [],
+          "stores": [
+            "shop.cart.pg"
+          ]
+        }
+      ]
+    }
+  ],
+  "defs": {},
+  "flows": [],
+  "adrs": [],
+  "stores": [
+    {
+      "id": "shop.cart.pg",
+      "slug": "pg",
+      "name": "Cart database",
+      "kind": "postgres",
+      "owner": "shop.cart",
+      "tables": [
+        {
+          "id": "shop.cart.pg.baskets",
+          "name": "baskets",
+          "columns": [
+            {
+              "name": "id",
+              "type": "uuid",
+              "nullable": false,
+              "pk": true,
+              "maps": "Basket.id"
+            },
+            {
+              "name": "token",
+              "type": "text",
+              "nullable": false,
+              "maps": "Basket.token"
+            },
+            {
+              "name": "customer_id",
+              "type": "text",
+              "nullable": true
+            },
+            {
+              "name": "currency",
+              "type": "char(3)",
+              "nullable": true
+            },
+            {
+              "name": "status",
+              "type": "text",
+              "nullable": false,
+              "maps": "Basket.status"
+            },
+            {
+              "name": "touched_at",
+              "type": "timestamptz",
+              "nullable": false,
+              "maps": "Basket.touchedAt"
+            },
+            {
+              "name": "version",
+              "type": "integer",
+              "nullable": false
+            }
+          ],
+          "indexes": [
+            {
+              "name": "baskets_open_by_customer",
+              "columns": [
+                "customer_id"
+              ],
+              "unique": false
+            },
+            {
+              "name": "baskets_idle",
+              "columns": [
+                "touched_at"
+              ],
+              "unique": false
+            }
+          ],
+          "persists": {
+            "aggregate": "shop.cart.basket"
+          },
+          "role": "aggregate-root"
+        },
+        {
+          "id": "shop.cart.pg.basket_items",
+          "name": "basket_items",
+          "columns": [
+            {
+              "name": "basket_id",
+              "type": "uuid",
+              "nullable": false,
+              "pk": true,
+              "fk": {
+                "table": "shop.cart.pg.baskets",
+                "column": "id",
+                "onDelete": "cascade"
+              },
+              "maps": "Basket.id"
+            },
+            {
+              "name": "sku",
+              "type": "text",
+              "nullable": false,
+              "pk": true,
+              "maps": "Basket.sku"
+            },
+            {
+              "name": "quantity",
+              "type": "integer",
+              "nullable": false,
+              "maps": "Basket.quantity"
+            },
+            {
+              "name": "unit_price_minor",
+              "type": "bigint",
+              "nullable": false,
+              "maps": "Basket.unitPrice.amountMinor"
+            },
+            {
+              "name": "currency",
+              "type": "char(3)",
+              "nullable": false,
+              "maps": "Basket.unitPrice.currency.code"
+            }
+          ],
+          "persists": {
+            "aggregate": "shop.cart.basket"
+          },
+          "role": "child"
+        },
+        {
+          "id": "shop.cart.pg.outbox",
+          "name": "outbox",
+          "columns": [
+            {
+              "name": "id",
+              "type": "bigserial",
+              "nullable": false,
+              "pk": true
+            },
+            {
+              "name": "uuid",
+              "type": "uuid",
+              "nullable": false
+            },
+            {
+              "name": "topic",
+              "type": "text",
+              "nullable": false
+            },
+            {
+              "name": "payload",
+              "type": "jsonb",
+              "nullable": false
+            },
+            {
+              "name": "metadata",
+              "type": "jsonb",
+              "nullable": false
+            },
+            {
+              "name": "created_at",
+              "type": "timestamptz",
+              "nullable": false
+            },
+            {
+              "name": "published_at",
+              "type": "timestamptz",
+              "nullable": true
+            }
+          ],
+          "indexes": [
+            {
+              "name": "outbox_unpublished",
+              "columns": [
+                "id"
+              ],
+              "unique": false
+            }
+          ],
+          "role": "outbox"
+        }
+      ],
+      "source": "examples/shop/cart/src/infrastructure/repository"
+    }
+  ]
+}

package/src/testing/estate/examples__shop__oms__portolan__glossary.json

@@ -0,0 +1,98 @@
+{
+  "generatedAt": "2026-09-05T06:21:10+07:00",
+  "commit": "1b88f52",
+  "contexts": [],
+  "defs": {},
+  "flows": [],
+  "adrs": [],
+  "terms": [
+    {
+      "id": "shop.basket",
+      "slug": "basket",
+      "context": "shop",
+      "name": "Basket",
+      "definition": "The cart's aggregate. An order carries its basket's id and is placed from it exactly once.",
+      "source": "examples/shop/oms/GLOSSARY.md:5"
+    },
+    {
+      "id": "shop.bus",
+      "slug": "bus",
+      "context": "shop",
+      "name": "Bus",
+      "definition": "NATS JetStream when configured, in process otherwise. One stream per service, named for its subjects.",
+      "source": "examples/shop/oms/GLOSSARY.md:8"
+    },
+    {
+      "id": "shop.cancelled",
+      "slug": "cancelled",
+      "context": "shop",
+      "name": "Cancelled",
+      "definition": "The order will not be fulfilled. Terminal.",
+      "source": "examples/shop/oms/GLOSSARY.md:11"
+    },
+    {
+      "id": "shop.confirmed",
+      "slug": "confirmed",
+      "context": "shop",
+      "name": "Confirmed",
+      "definition": "The payment is authorised; the order may be fulfilled.",
+      "source": "examples/shop/oms/GLOSSARY.md:13"
+    },
+    {
+      "id": "shop.line",
+      "slug": "line",
+      "context": "shop",
+      "name": "Line",
+      "definition": "One SKU of the order, how many, and the unit price it was added to the basket at. Copied, never repriced.",
+      "source": "examples/shop/oms/GLOSSARY.md:15"
+    },
+    {
+      "id": "shop.money",
+      "slug": "money",
+      "context": "shop",
+      "name": "Money",
+      "definition": "An amount in the minor unit of a currency.",
+      "source": "examples/shop/oms/GLOSSARY.md:18"
+    },
+    {
+      "id": "shop.order",
+      "slug": "order",
+      "context": "shop",
+      "name": "Order",
+      "definition": "What a basket became at checkout: the lines and the total the customer agreed to, under one lock. The aggregate root.",
+      "source": "examples/shop/oms/GLOSSARY.md:20"
+    },
+    {
+      "id": "shop.outbox",
+      "slug": "outbox",
+      "context": "shop",
+      "name": "Outbox",
+      "definition": "The table an event waits in, written in the transaction that produced it, until the relay puts it on the bus.",
+      "source": "examples/shop/oms/GLOSSARY.md:23"
+    },
+    {
+      "id": "shop.payments",
+      "slug": "payments",
+      "context": "shop",
+      "name": "Payments",
+      "definition": "The ledger that authorises an order's total. A port here; nothing provides it yet.",
+      "source": "examples/shop/oms/GLOSSARY.md:26"
+    },
+    {
+      "id": "shop.placed",
+      "slug": "placed",
+      "context": "shop",
+      "name": "Placed",
+      "definition": "The order exists and is waiting for its payment to be authorised. Where every order starts.",
+      "source": "examples/shop/oms/GLOSSARY.md:29"
+    },
+    {
+      "id": "shop.relay",
+      "slug": "relay",
+      "context": "shop",
+      "name": "Relay",
+      "definition": "The loop that moves outbox rows to the bus and marks them published.",
+      "source": "examples/shop/oms/GLOSSARY.md:32"
+    }
+  ]
+}

package/src/testing/estate/examples__shop__oms__portolan__proto.json

@@ -0,0 +1,186 @@
+{
+  "generatedAt": "2026-09-05T01:16:26+07:00",
+  "commit": "1d17393",
+  "contexts": [
+    {
+      "id": "shop",
+      "slug": "shop",
+      "name": "",
+      "summary": "",
+      "services": [
+        {
+          "id": "shop.oms",
+          "slug": "oms",
+          "name": "",
+          "repo": "",
+          "path": "",
+          "readme": "",
+          "provides": [
+            {
+              "id": "shop.v1.OrderService",
+              "methods": [
+                {
+                  "name": "GetOrder",
+                  "doc": "GetOrder answers with the order as it is now. NOT_FOUND for an id the\nservice has never seen; a cancelled order is still found.",
+                  "request": "GetOrderRequest",
+                  "response": "GetOrderResponse"
+                },
+                {
+                  "name": "CancelOrder",
+                  "doc": "CancelOrder cancels an order that has not been dispatched yet.\nFAILED_PRECONDITION once it has: from then on the way back is a return,\nwhich is delivery's business, not this service's. Cancelling twice is\nnot an error; the second call answers with the already cancelled order.",
+                  "request": "CancelOrderRequest",
+                  "response": "CancelOrderResponse"
+                }
+              ],
+              "source": "examples/shop/oms/vendor/proto/shortlink-org/portolan-shop-order/shop/v1/orders.proto:14",
+              "messages": [
+                {
+                  "name": "GetOrderRequest",
+                  "fields": [
+                    {
+                      "name": "order_id",
+                      "type": "string",
+                      "doc": ""
+                    }
+                  ]
+                },
+                {
+                  "name": "GetOrderResponse",
+                  "fields": [
+                    {
+                      "name": "order",
+                      "type": "Order",
+                      "doc": ""
+                    }
+                  ]
+                },
+                {
+                  "name": "CancelOrderRequest",
+                  "fields": [
+                    {
+                      "name": "order_id",
+                      "type": "string",
+                      "doc": ""
+                    }
+                  ]
+                },
+                {
+                  "name": "CancelOrderResponse",
+                  "fields": [
+                    {
+                      "name": "order",
+                      "type": "Order",
+                      "doc": ""
+                    }
+                  ]
+                },
+                {
+                  "name": "Order",
+                  "fields": [
+                    {
+                      "name": "id",
+                      "type": "string",
+                      "doc": ""
+                    },
+                    {
+                      "name": "customer_id",
+                      "type": "string",
+                      "doc": "The customer auth vouched for at checkout. Opaque here, as everywhere."
+                    },
+                    {
+                      "name": "basket_id",
+                      "type": "string",
+                      "doc": "The basket this order was placed from, so a reader can walk back to it."
+                    },
+                    {
+                      "name": "status",
+                      "type": "OrderStatus",
+                      "doc": ""
+                    },
+                    {
+                      "name": "lines",
+                      "type": "[]Line",
+                      "doc": ""
+                    },
+                    {
+                      "name": "total",
+                      "type": "Money",
+                      "doc": "The quoted total, tax and promotions included."
+                    },
+                    {
+                      "name": "placed_at",
+                      "type": "Timestamp",
+                      "doc": ""
+                    }
+                  ]
+                },
+                {
+                  "name": "Line",
+                  "fields": [
+                    {
+                      "name": "sku",
+                      "type": "string",
+                      "doc": ""
+                    },
+                    {
+                      "name": "quantity",
+                      "type": "int32",
+                      "doc": ""
+                    },
+                    {
+                      "name": "unit_price",
+                      "type": "Money",
+                      "doc": ""
+                    }
+                  ]
+                },
+                {
+                  "name": "Money",
+                  "fields": [
+                    {
+                      "name": "amount_minor",
+                      "type": "int64",
+                      "doc": ""
+                    },
+                    {
+                      "name": "currency",
+                      "type": "string",
+                      "doc": ""
+                    }
+                  ]
+                }
+              ],
+              "module": "buf.build/shortlink-org/portolan-shop-order"
+            }
+          ],
+          "consumes": [],
+          "aggregates": [],
+          "modules": [
+            "buf.build/shortlink-org/portolan-shop-order"
+          ]
+        }
+      ]
+    }
+  ],
+  "defs": {},
+  "flows": [],
+  "adrs": [],
+  "modules": [
+    {
+      "id": "buf.build/shortlink-org/portolan-shop-order",
+      "slug": "shortlink-org-portolan-shop-order",
+      "name": "shortlink-org/portolan-shop-order",
+      "registry": "buf.build",
+      "owner": "shop.oms",
+      "commit": "6ae5e6ade8a547a59553b3aae02a2335",
+      "digest": "b5:98cb137b4f89cdc545fec4d960a0d2fa57bc89e3a91803e305d7e19e52a12260d97642a4df82c3f97887fea0c25c976db3df9754b0eb3e09f39ceecfa21f7d92",
+      "packages": [
+        "shop.v1"
+      ],
+      "files": [
+        "shop/v1/orders.proto"
+      ],
+      "source": "examples/shop/oms/vendor/proto/shortlink-org/portolan-shop-order"
+    }
+  ]
+}

package/src/testing/estate.ts

@@ -0,0 +1,49 @@
+// The estate the UI tests are written against: a frozen copy of the sources
+// as they were on 2026-09-05, before the hand-written order service made way
+// for the real one. It holds the shapes the real services do not - a flow with
+// parallel branches, a store with foreign keys, indexes, views and lineage, an
+// ADR that relates to a flow - and it does not move when a service is added or
+// a fragment is regenerated, which is what a fixture is for. Tests about what
+// the app actually ships import `../data` instead.
+//
+// Built the way `src/data.ts` builds the live catalog: merged, enriched,
+// validated, indexed. A fixture that failed validation would be a test of
+// nothing, so that failure throws here.
+//
+// `data__catalog.json` carries no stamp, exactly as its original does not: a
+// file no plugin produces is generated by nobody, and freezing a provenance
+// somebody typed would freeze the one shape the merge is written to ignore.
+
+import { buildIndex, validateCatalog } from "../catalog";
+import type { Catalog, CatalogIndex } from "../catalog";
+import { enrichCatalog } from "../enrich";
+import type { DerivedEdge } from "../enrich";
+import { mergeCatalogs } from "../merge";
+import type {
+  CatalogSource,
+  MergeConflict,
+  SourceCatalog,
+  SourceStamp,
+} from "../merge";
+
+// A file is named for the path its source had, with `__` for `/`, so the
+// stamps the merge records read the way they did when the estate was live.
+const modules: Record<string, unknown> = import.meta.glob("./estate/*.json", { eager: true, import: "default" });
+
+const sources: CatalogSource[] = Object.entries(modules)
+  .map(([file, catalog]) => ({
+    path: file.replace(/^\.\/estate\//, "").replace(/__/g, "/"),
+    catalog: catalog as SourceCatalog,
+  }))
+  .sort((a, b) => a.path.localeCompare(b.path));
+
+const merged = mergeCatalogs(sources);
+const enriched = enrichCatalog(merged.catalog);
+
+export const catalog: Catalog = validateCatalog(enriched.catalog);
+export const index: CatalogIndex = buildIndex(catalog);
+export const catalogSources: SourceStamp[] = merged.sources;
+export const catalogConflicts: MergeConflict[] = merged.conflicts;
+export const derivedEdges: DerivedEdge[] = enriched.derived;
+/** The sources as merged, before anything was derived or checked. */
+export const rawCatalog: Catalog = merged.catalog;

package/src/trail/Trail.tsx

@@ -0,0 +1,81 @@
+// The trail, as a strip under the top bar.
+//
+// It is chrome, so it is quiet: one row, no borders around the chips, the
+// icons doing the work of saying what each name is. The page the reader is on
+// is in the row too, dimmed and not a link — it is there so the strip does not
+// shift under them on every move, not as somewhere to go.
+
+import { useMemo } from "react";
+import { History } from "lucide-react";
+import { Link, useLocation } from "react-router";
+import { KindIcon } from "../components/kind";
+import { KIND_LABEL } from "../lib/kinds";
+import { useNarrow } from "../app/responsive";
+import { visitSubject, visitTo } from "./model";
+import { useTrailStore } from "./store";
+
+const CHIP = "mono flex shrink-0 items-center gap-1.5 rounded-control px-1.5 py-px";
+
+export function Trail() {
+  const visits = useTrailStore((s) => s.visits);
+  const { pathname } = useLocation();
+  const narrow = useNarrow();
+
+  // Entities the catalog has since dropped leave the strip rather than
+  // offering a link to a page that is not there any more.
+  const chips = useMemo(
+    () =>
+      visits.flatMap((visit) => {
+        const subject = visitSubject(visit);
+        return subject ? [{ visit, subject }] : [];
+      }),
+    [visits],
+  );
+
+  // One chip is not a trail, it is the page the reader is already looking at;
+  // and below the breakpoint the shell has no rows to spare.
+  if (narrow || chips.length < 2) return null;
+
+  return (
+    <nav
+      aria-label="Recently visited"
+      className="flex h-8 shrink-0 items-center gap-1 overflow-x-auto border-b px-gutter border-line bg-canvas"
+    >
+      <History
+        size={13}
+        aria-hidden
+        className="mr-1 shrink-0 text-line-strong"
+      />
+      {chips.map(({ visit, subject }) =>
+        visit.path === pathname ? (
+          <span
+            key={visit.path}
+            aria-current="page"
+            className={`${CHIP} text-muted opacity-50`}
+          >
+            <KindIcon
+              kind={subject.kind}
+              contextId={subject.contextId}
+              size={13}
+            />
+            {subject.label}
+          </span>
+        ) : (
+          <Link
+            key={visit.path}
+            to={visitTo(visit)}
+            title={`${KIND_LABEL[subject.kind]} — ${subject.label}`}
+            className={`${CHIP} text-muted t-micro transition-colors hover:bg-surface hover:text-ink`}
+          >
+            <KindIcon
+              kind={subject.kind}
+              contextId={subject.contextId}
+              size={13}
+            />
+            {subject.label}
+          </Link>
+        ),
+      )}
+    </nav>
+  );
+}