@shortlink-org/portolan 0.3.0 → 0.4.0

package/scripts/warning-policy.mjs

@@ -21,25 +21,31 @@ const ENVIRONMENT = new Environment({
 const COMPILED = new Map();
 
 const RULES = [
-  rule("openapi.missing-operation-id", /\bhas no operationId\b/i, "warning", "Add stable operationId values to the OpenAPI operations."),
+  rule("openapi.missing-operation-id", /\bno operationId\b/i, "warning", "Add stable operationId values to the OpenAPI operations."),
   rule("schema.duplicate-declaration", /\bduplicate declaration\b/i, "warning", "Remove or reconcile duplicate schema declarations; Portolan currently uses the first."),
   rule("analysis.typed-fallback", /\btyped call graph unavailable\b/i, "warning", "Run an extractor build with typed analysis support or inspect calls found by the syntax fallback."),
   rule("catalog.unresolved-call", /\bcalls .+ which nothing in this catalog resolves\b/i, "warning", "Add or correct the provider contract, then regenerate to resolve the call."),
-  rule("catalog.unmapped-proto-peer", /\bmanifest names no peer for that package\b/i, "warning", "Map the protobuf package under peers, or declare it under externals."),
+  rule("catalog.unmapped-proto-peer", /\bmanifest names no peer for (?:that package|it)\b/i, "warning", "Map the protobuf package under peers, or declare it under externals."),
   rule("flow.unresolved-step", /\bstep .+ is unresolved\b/i, "warning", "Declare the referenced endpoint, message, or store so this flow step can be joined."),
-  rule("flow.unknown-port", /\bis neither a domain port nor a use case\b/i, "warning", "Model this dependency as a domain port or use case, or accept that its calls stay outside the flow."),
+  rule("flow.unknown-port", /\bis neither a domain port(?:,| nor) a use case\b/i, "warning", "Model this dependency as a domain port or use case, or accept that its calls stay outside the flow."),
   rule("flow.unreached-event", /\bno flow reaches this event\b/i, "warning", "Connect the event to its publisher flow or remove the stale event declaration."),
   rule("flow.unknown-event", /\breacts to the message named .+ which no event .+ declares is called\b/i, "warning", "Declare the event name used by the handler or correct the handler mapping."),
   rule("django.invalid-aggregate-root", /\baggregates names .+ and no model there is called that\b/i, "warning", "Choose an existing concrete model for the application's aggregates option."),
-  rule("django.ambiguous-aggregate-root", /\bmodels to choose from: name the root in the aggregates option\b/i, "warning", "Choose the aggregate root explicitly in the django-domain aggregates option."),
   rule("django.unknown-http-verb", /\bmounted as an HTTP view, but no HTTP verb is declared\b/i, "warning", "Declare the accepted HTTP methods on the view or route."),
   rule("river.missing-worker", /\bno registered Worker\b/i, "warning", "Register the River worker in this component or remove the unmatched insert."),
-  rule("watermill.unresolved-topic", /\bWatermill .+ topic could not be resolved\b/i, "warning", "Use a literal, constant, or configuration default for the Watermill topic."),
+  rule("watermill.unresolved-topic", /\bWatermill .+\btopic (?:generator could not be resolved|unresolved)\b/i, "warning", "Use a literal, constant, or configuration default for the Watermill topic."),
   rule("messaging.unresolved-subject", /\bsubject of .+ could not be resolved\b/i, "warning", "Use a literal, constant, configuration default, or visible caller argument for the subject."),
+  rule("messaging.unresolved-queue", /\bqueue of .+ could not be resolved\b/i, "warning", "Use a literal, constant, configuration default, constructor argument, or visible caller argument for the queue."),
+  rule("terraform.unresolved-name", /\b(?:could not be resolved to a literal, a variable default, a local or a module argument|is named with \w+_prefix, so its name is decided at apply time|sets no \w+, so its name is decided at apply time)\b/i, "warning", "Name the resource with a literal, a variable default, a local or a module argument so the catalog can address it."),
+  rule("terraform.name-at-apply-time", /\bis `[^`]*`, with .+ decided at apply time\b/i, "info", "The literal part of the name is listed; the rest is filled when Terraform applies."),
+  rule("terraform.unresolved-reference", /\bcould not be followed to (?:a queue, a table or a stream|an? \w+(?: \w+)*) declared here\b/i, "warning", "Reference the resource by its Terraform address, or declare it in this module."),
+  rule("terraform.module-skipped", /\bmodule ".+" (?:comes from|calls) .+ and is not read\b/i, "info", "Vendor the module under the input root to have its resources read."),
+  rule("terraform.not-read", /\bis not read: .+ is not part of this reader yet\b/i, "info", "This AWS product is not modelled yet; the resource is listed so the gap is visible."),
   rule("store.external-migrations", /\bmigrations are applied from .+ whose schema is not in this tree\b/i, "warning", "Vendor or expose the external migrations so their tables can be included in the store."),
   rule("store.missing-foreign-table", /\bcolumn .+ references .+ which no migration here creates\b/i, "warning", "Include the referenced table migration or correct the foreign-key target."),
   rule("schema.unresolved-type", /\bis not declared in the protos read here\b/i, "warning", "Include the imported protobuf declaration or map the type to an external schema."),
-  rule("source.offline-cache", /\bnot fetched \(offline\)\b/i, "info", "Regenerate with network access when the vendored copy must be refreshed."),
+  rule("source.offline-cache", /\bnot (?:fetched|read) \(offline\)/i, "info", "Regenerate with network access when the vendored copy must be refreshed."),
+  rule("source.unreachable", /\bnot (?:fetched|read) \((?!offline\))/i, "warning", "The far end could not be reached and the committed copy was used; check the server and the credential, then regenerate."),
   rule("source.unpinned", /\bnot pinned\b/i, "warning", "Pin the source to an immutable commit or schema version."),
   rule("source.parse-failed", /\bcould not (?:be read|parse|be parsed|be encoded)\b/i, "error", "Open the referenced source and fix the parse or read error."),
   rule("extraction.no-match", /\b(?:no .+ (?:was|were) found|no .+ matched|declares no |no models in this application)\b/i, "info", "Confirm this capability is absent, or point the extractor at the source that declares it."),

package/scripts/warning-policy.test.mjs

@@ -1,10 +1,10 @@
 import { describe, expect, it } from "vitest";
-import { diagnoseWarnings, warningPolicyProblems } from "./warning-policy.mjs";
+import { classifyWarning, diagnoseWarnings, warningPolicyProblems } from "./warning-policy.mjs";
 
 describe("warning CEL policies", () => {
   const warnings = [
-    "api: /book POST has no operationId; listed by verb and path",
-    "api: /cancel POST has no operationId; listed by verb and path",
+    "aviacore-api: no operationId on 53 of 53 operations; listed by verb and path: GET /a, POST /b and 51 more",
+    "aviasupp-api: no operationId on 2 of 9 operations; listed by verb and path: POST /book, POST /cancel",
   ];
 
   it("evaluates typed CEL over the diagnostic and its repetition count", () => {
@@ -54,3 +54,40 @@ describe("warning CEL policies", () => {
     ]);
   });
 });
+
+describe("warning classification", () => {
+  // Each message is worded the way the plugin that emits it words it today
+  // (grep the plugin for the phrase before editing a rule), so a policy that
+  // names the rule keeps matching during generation.
+  const emitted = [
+    ["openapi", "aviacore-api: no operationId on 53 of 53 operations; listed by verb and path: GET /a, POST /b and 51 more", "openapi.missing-operation-id"],
+    ["go-domain", "calls ledger.v1 and the manifest names no peer for that package; add it under `peers` to say which service answers, or under `externals` when the far end is outside the estate, until then the calls are unresolved", "catalog.unmapped-proto-peer"],
+    ["java-domain", "calls ledger.v1 and the manifest names no peer for it; add it under `peers` to say which service answers, or under `externals` when the far end is outside the estate, until then the calls are unresolved", "catalog.unmapped-proto-peer"],
+    ["go-domain", "internal/app: port `clock Clock` is neither a domain port nor a use case; its calls are left out of the flow", "flow.unknown-port"],
+    ["rust-domain", "src/app.rs: port `clock: Clock` is neither a domain port, a use case nor a client; its calls are left out of the flow", "flow.unknown-port"],
+    ["watermill", "internal/bus/router.go:12:3: Watermill handler orders is registered on topic `cfg.Topic`, which this reader cannot resolve to a literal, a constant, a config default or a caller's argument; the handler is kept with its topic unresolved", "watermill.unresolved-topic"],
+    ["watermill", "internal/bus/cqrs.go:40:5: Watermill CQRS handler topic generator could not be resolved", "watermill.unresolved-topic"],
+    ["go-nats", "internal/pub.go:8:2: subject of Publish could not be resolved to a literal, a constant, a config default or a caller's argument", "messaging.unresolved-subject"],
+    ["go-sqs", "internal/relay.go:15:2: queue of SendMessage could not be resolved to a literal, a constant, a config default, a constructor's argument or a caller's argument", "messaging.unresolved-queue"],
+    ["terraform", "deploy/queues.tf:12: name of aws_sqs_queue.opaque could not be resolved to a literal, a variable default, a local or a module argument", "terraform.unresolved-name"],
+    ["terraform", "deploy/queues.tf:40: aws_sqs_queue.generated is named with name_prefix, so its name is decided at apply time and is not read", "terraform.unresolved-name"],
+    ["terraform", "deploy/lambda.tf:52: aws_lambda_function.unnamed sets no function_name, so its name is decided at apply time and is not read", "terraform.unresolved-name"],
+    ["terraform", "deploy/data.tf:80: name of aws_sqs_queue.per_account is `fulfillment-events-{account_id}`, with {account_id} decided at apply time", "terraform.name-at-apply-time"],
+    ["terraform", "deploy/lambda.tf:30: event_source_arn of aws_lambda_event_source_mapping.in could not be followed to a queue, a table or a stream declared here", "terraform.unresolved-reference"],
+    ["terraform", "deploy/lambda.tf:30: function_name of aws_lambda_event_source_mapping.in could not be followed to an aws_lambda_function declared here", "terraform.unresolved-reference"],
+    ["terraform", "deploy/main.tf:36: module \"vpc\" comes from terraform-aws-modules/vpc/aws, which is not in this tree, and is not read", "terraform.module-skipped"],
+    ["terraform", "deploy/data.tf:69: aws_kinesis_stream.clicks is not read: Kinesis is not part of this reader yet", "terraform.not-read"],
+    ["git", "github.com/acme/ledger: not fetched (offline); the copy committed in this repository is used unchanged", "source.offline-cache"],
+    ["markdown", "flow.checkout step \"pay\" is unresolved: POST /pay", "flow.unresolved-step"],
+    ["rust-domain", "Confirm: src/policy.rs: Confirm.handle reacts to the message named \"payment.authorized\", which no event this repository declares is called; the step is unresolved", "flow.unknown-event"],
+  ];
+
+  it.each(emitted)("classifies what %s emits to a stable rule", (plugin, message, rule) => {
+    expect(classifyWarning(plugin, message).rule).toBe(rule);
+  });
+
+  it("no longer carries a rule for a warning no plugin emits", () => {
+    const message = "billing/records: no model called Records, and 2 models to choose from: name the root in the aggregates option";
+    expect(classifyWarning("django-domain", message).rule).toMatch(/^plugin\.django-domain\.other-/);
+  });
+});

package/src/app/Breadcrumbs.test.ts

@@ -10,6 +10,9 @@ describe("crumbsFor", () => {
     expect(crumbsFor("/language")).toEqual([
       { label: "language", to: "/language" },
     ]);
+    expect(crumbsFor("/plugins")).toEqual([
+      { label: "plugins", to: "/plugins" },
+    ]);
     expect(crumbsFor("/problems")).toEqual([
       { label: "problems", to: "/problems" },
     ]);

package/src/app/Breadcrumbs.tsx

@@ -85,6 +85,9 @@ export function crumbsFor(pathname: string): Crumb[] {
   if (parts[0] === "problems")
     return [{ label: "problems", to: paths.problems() }];
 
+  if (parts[0] === "plugins")
+    return [{ label: "plugins", to: paths.plugins() }];
+
   if (parts[0] === "registry") {
     const crumbs: Crumb[] = [{ label: "registry", to: paths.registry() }];
     const slug = parts[1];

package/src/app/CatalogApp.tsx

@@ -18,6 +18,7 @@ import { FlowDetail } from "../pages/FlowDetail";
 import { FlowIndex } from "../pages/FlowIndex";
 import { AdrIndex } from "../pages/AdrIndex";
 import { Language } from "../pages/Language";
+import { PluginIndex } from "../pages/PluginIndex";
 import { AdrDetail } from "../pages/AdrDetail";
 import { Overview } from "../pages/Overview";
 import { ContextMap } from "../pages/ContextMap";
@@ -119,6 +120,7 @@ function AppRoutes({
       />
       <Route path="/adrs" element={<AdrIndex />} />
       <Route path="/language" element={<Language />} />
+      <Route path="/plugins" element={<PluginIndex />} />
       <Route path="/adrs/:adr" element={<AdrDetail />} />
       <Route path="/problems" element={<Problems />} />
       <Route path="/settings/*" element={<Settings />} />

package/src/app/SidebarFooter.tsx

@@ -1,17 +1,17 @@
-import { useMemo } from "react";
 import { NavLink } from "react-router";
 import {
   Check,
   PanelLeftOpen,
+  Puzzle,
   Settings2,
   TriangleAlert,
 } from "lucide-react";
 
 import { allModules } from "../catalog";
+import { catalog } from "../data";
 import { KindIcon } from "../components/kind";
 import { CompassRose } from "../components/logo";
-import { catalog, index } from "../data";
-import { allProblems } from "../lib/all-problems";
+import { useProblems } from "../lib/use-problems";
 import type { Kind } from "../lib/kinds";
 import { paths } from "../routes";
 
@@ -28,7 +28,7 @@ export function SidebarBottomGroup() {
   // opens. The badge is red while anything on it is an error and amber when
   // only the schema disagrees with itself - a page of warnings is not a clean
   // estate, and a green tick over it would be the one lie the row can tell.
-  const found = useMemo(() => allProblems(catalog, index), []);
+  const found = useProblems();
   const errors = found.filter((p) => p.severity === "error").length;
   const colour =
     errors > 0 ? "var(--status-unresolved)" : "var(--status-declared)";
@@ -76,6 +76,22 @@ export function SidebarBottomGroup() {
           </span>
         )}
       </NavLink>
+      <NavLink
+        to={paths.plugins()}
+        data-nav-item
+        title="Plugins — what Portolan can read, and what it makes"
+        style={({ isActive }) => ({
+          paddingLeft: indent(0),
+          background: isActive ? "var(--surface-2)" : undefined,
+          borderLeftWidth: 2,
+          borderLeftStyle: "solid",
+          borderLeftColor: isActive ? "var(--accent)" : "transparent",
+        })}
+        className="tree-row flex items-center gap-1.5 py-[3px] pr-2 text-muted t-micro transition-colors hover:bg-surface hover:text-ink"
+      >
+        <Puzzle size={14} aria-hidden className="block shrink-0" />
+        <span className="truncate">Plugins</span>
+      </NavLink>
       <NavLink
         to={paths.settings()}
         data-nav-item

package/src/catalog-index.ts

@@ -6,6 +6,7 @@ import type {
   BoundedContext,
   Catalog,
   Column,
+  Deployment,
   Enum,
   Event,
   External,
@@ -21,12 +22,14 @@ import type {
   View,
 } from "./catalog-model.ts";
 import {
+  allDeployments,
   allExternals,
   allModules,
   allStores,
   allTerms,
   aggregateBlocks,
   columnId,
+  deploys,
   enumsOf,
   storeViews,
   viewReads,
@@ -140,6 +143,14 @@ export interface CatalogIndex {
   lineageInto: Map<string, string[]>;
   /** service id -> stores it owns, in catalog order */
   storesOwnedBy: Map<string, Store[]>;
+  /**
+   * service id -> where it runs, in snapshot order.
+   *
+   * Joined here rather than written by the fetcher, which reads a control
+   * plane and knows no service: an Application is this service's when it
+   * deploys from the service's repository, inside the service's directory.
+   */
+  deploymentsByService: Map<string, Deployment[]>;
   /** aggregate id -> tables naming it in `persists`, in catalog order */
   tablesByAggregate: Map<string, Table[]>;
   /** aggregate id -> views naming it in `persists`, in catalog order */
@@ -323,6 +334,19 @@ export function buildIndex(catalog: Catalog): CatalogIndex {
     }
   }
 
+  // Deployments come after the services because the join runs over them: a
+  // row is placed on every service whose repository and directory it deploys
+  // from, and on none when nobody in the estate claims that repository.
+  const deploymentsByService = new Map<string, Deployment[]>();
+  for (const deployment of allDeployments(catalog)) {
+    for (const service of serviceById.values()) {
+      if (!deploys(deployment, service)) continue;
+      const placed = deploymentsByService.get(service.id) ?? [];
+      placed.push(deployment);
+      deploymentsByService.set(service.id, placed);
+    }
+  }
+
   // Stores come after the domain tree because they point into it: a table says
   // which aggregate it persists, and a column which block it maps to, so both
   // are resolved against maps that are already full.
@@ -467,6 +491,7 @@ export function buildIndex(catalog: Catalog): CatalogIndex {
     lineageFrom,
     lineageInto,
     storesOwnedBy,
+    deploymentsByService,
     moduleById,
     moduleBySlug,
     interfacesByModule,

package/src/catalog-model.ts

@@ -44,6 +44,13 @@ export interface Catalog {
    * to pin and renders as it did before there was anything to pin.
    */
   repos?: RepoPin[];
+  /**
+   * Where the estate's services run, read from what deploys them. Optional
+   * in the file and never optional downstream, exactly like `repos`: an
+   * estate nobody has pointed at a deployer renders as it did before there
+   * was anything to place.
+   */
+  deployments?: Deployment[];
   /**
    * The systems outside the estate that a service calls on a contract: a
    * payment provider, a tax API, a carrier. Nobody here builds one, so it has
@@ -173,6 +180,24 @@ export interface Service {
    * same as a service that cannot be built.
    */
   commands?: Command[];
+  /**
+   * The names this service answers on, read from what deploys it: a
+   * Kubernetes Service's name in its short, namespaced, `svc` and fully
+   * qualified forms, and the hosts of the Ingress or HTTPRoute in front of
+   * it. Written so that a call another service is configured to make to
+   * `pricing.shop.svc` can find the service that answers. Absent when
+   * nothing in the tree says where the service is reachable.
+   */
+  hosts?: string[];
+  /**
+   * The in-cluster names this service's workload is configured to reach,
+   * read out of its environment and config maps and reduced to the host
+   * alone. A value is never kept: not the variable it came from, not the
+   * scheme, port, path or credentials around the name. Only a name the
+   * cluster resolves qualifies, so a password in an environment variable is
+   * not something this list can hold by shape.
+   */
+  dials?: string[];
 }
 
 /**
@@ -377,7 +402,7 @@ export interface HTTPDestination {
   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 };
+  resolution?: { basis: "full-path" | "exact-route" | "unique-suffix" | "kubernetes-host"; provider: string; route: string };
 }
 export interface HTTPBaseURL {
   expression: string;
@@ -471,6 +496,104 @@ export interface RepoPin {
   /** The commit the copy was made of. Full sha: it is not resolved locally, so there is nothing to expand it against. */
   commit: string;
 }
+
+/**
+ * One place a service runs: an Argo CD Application, as the deployer listed
+ * it, reduced to what a deploy changes.
+ *
+ * A list on the catalog rather than a field on `Service`, for two reasons.
+ * The fetcher that writes it reads a control plane, not a service's tree, so
+ * it does not know which service an Application is; the join is made where
+ * the whole estate is known, by the repository and path the Application
+ * deploys from against the ones a service says it lives at. And one service
+ * stands in several places - staging, production, a second region - and
+ * each is its own row.
+ *
+ * Nothing here moves without a deploy. Health, sync state and the time of
+ * the last operation move on their own, and a page regenerated from the
+ * tree cannot follow them; they are not kept.
+ */
+export interface Deployment {
+  /** `<argocd namespace>/<application name>`: unique per control plane. */
+  id: string;
+  /** The Application's name, as `argocd app get` takes it. */
+  name: string;
+  /** The Argo CD project it belongs to. */
+  project: string;
+  /**
+   * Where a reader would say it runs: the application's environment label,
+   * else the cluster it deploys to. What the page groups by.
+   */
+  environment: string;
+  /** The destination cluster, by its Argo CD name; `in-cluster` for the one Argo CD runs in. */
+  cluster: string;
+  /** The destination namespace. */
+  namespace: string;
+  /** The repository it deploys from, spelled the way `Service.repo` spells it. Empty for a chart from a registry. */
+  repo: string;
+  /** The directory in that repository the manifests are read from, as a reader would type it. Empty for a chart. */
+  path: string;
+  /** The Helm chart name, when the source is a chart registry rather than a repository. */
+  chart?: string;
+  /** What the Application tracks: a branch, a tag, a chart version. */
+  targetRevision: string;
+  /** What is deployed now: the commit, or chart version, the last sync resolved `targetRevision` to. */
+  revision: string;
+  /** `helm`, `kustomize`, `directory` or `plugin`, as Argo CD says it; empty until it has said. */
+  tool: string;
+  /** The Application in the Argo CD UI. */
+  url: string;
+  /**
+   * The service it deploys, by id, when the Application's labels say so:
+   * `app.kubernetes.io/part-of` and `app.kubernetes.io/name`, the same
+   * labels a workload carries. A GitOps repository's Application points at
+   * an overlay, not at the service's directory, so the path alone cannot
+   * place it; the labels can, and an ApplicationSet stamps them on every
+   * Application it makes. Absent when the labels are, and the path decides.
+   */
+  service?: string;
+  /** The container images the deployed resources run, as the deployer summarised them, sorted. */
+  images?: string[];
+  /**
+   * Who said so. `manifest` is a row an extractor read out of a GitOps
+   * tree: what should run. `api` is a row a fetcher read off the deployer:
+   * what does. `both` is one the merge folded from the two, which is the
+   * ordinary case for an estate that keeps both, and the only one that can
+   * carry drift. Absent reads as `api`, which is what every row was before
+   * there were trees to read.
+   */
+  basis?: DeploymentBasis;
+  /**
+   * What the tree says where it and the deployer disagree, set by the merge
+   * when both spoke (portolan.0013). A field is present only when the two
+   * differ; a row with no drift has no field at all.
+   */
+  drift?: DeploymentDrift;
+}
+
+export type DeploymentBasis = "manifest" | "api" | "both";
+
+export const DEPLOYMENT_BASES: readonly DeploymentBasis[] = [
+  "manifest",
+  "api",
+  "both",
+] as const;
+
+/** The GitOps tree's word on the fields where the deployer says otherwise. */
+export interface DeploymentDrift {
+  project?: string;
+  cluster?: string;
+  namespace?: string;
+  path?: string;
+  targetRevision?: string;
+  /** The images the overlay pins, when they are not the ones running. */
+  images?: string[];
+}
+
+/** The basis a row carries, `api` when it carries none. */
+export function deploymentBasis(deployment: Deployment): DeploymentBasis {
+  return deployment.basis ?? "api";
+}
 export interface Aggregate {
   id: string;
   slug: string;
@@ -537,6 +660,15 @@ export interface Operation {
    * estate can only reach from inside, which is sometimes exactly the point.
    */
   exposedBy?: string[];
+  /**
+   * What the caller hands in: the command's or query's own shape, as the
+   * message class declares it - the fields of `CreateCourseCommand`. Absent
+   * when the extractor does not read messages; empty is a message that
+   * carries nothing, `FindCoursesCounterQuery`.
+   */
+  fields?: Field[];
+  /** Where the handler is, `path:line`, for the reader who wants the code. */
+  source?: string;
 }
 
 /**
@@ -687,7 +819,31 @@ export interface Field {
   ref?: string;
   /** Protobuf field number; absent for sources whose wire has no field numbers. */
   number?: number;
+  /**
+   * The source says the field must be sent: a Protovalidate `required`, a
+   * name in a JSON Schema `required` list. Absent means the source does not
+   * say, which in proto3 and OpenAPI alike means it may be left out.
+   */
+  required?: boolean;
+  /** What the source says a value must satisfy, in the order it said it. */
+  rules?: FieldRule[];
 } // ref -> defs key
+/**
+ * One constraint on a field's value, in the catalog's own vocabulary so a
+ * Protovalidate `min_len` and a JSON Schema `minLength` are one rule:
+ * `min_len`, `max_len`, `len`, `pattern`, `prefix`, `suffix`, `contains`,
+ * `not_contains`, `format`, `gt`, `gte`, `lt`, `lte`, `const`, `in`,
+ * `not_in`, `multiple_of`, `min_items`, `max_items`, `unique`, `min_pairs`,
+ * `max_pairs`, `defined_only`, `lt_now`, `gt_now`, `cel`. A rule on what a
+ * list holds is prefixed `items.`; on a map's keys or values, `keys.` or
+ * `values.`. A custom option the catalog has no word for keeps the name the
+ * source gave it, `(acme.pii)`, so it is shown rather than lost.
+ */
+export interface FieldRule {
+  name: string;
+  /** The bound as the source wrote it, text so a 64-bit number survives; absent for a bare flag such as `unique`. */
+  value?: string;
+}
 export interface TypeDef {
   fields: Field[];
 }
@@ -710,6 +866,7 @@ export type StoreKind =
   | "mongodb"
   | "clickhouse"
   | "s3"
+  | "dynamodb"
   | "other";
 
 export const STORE_KINDS: readonly StoreKind[] = [
@@ -720,6 +877,7 @@ export const STORE_KINDS: readonly StoreKind[] = [
   "mongodb",
   "clickhouse",
   "s3",
+  "dynamodb",
   "other",
 ] as const;
 
@@ -918,6 +1076,47 @@ export interface Flow {
   owner: string;
   participants: Participant[]; // order is significant - it is the lane order
   steps: FlowNode[];
+  /**
+   * Recordings of this flow running: one per trace a verifier kept, each
+   * naming the steps it showed with what the spans said about them. Examples
+   * of data, not evidence - the evidence is the status on the step.
+   */
+  examples?: FlowExample[];
+}
+/** One recorded run of a flow, read from one trace. */
+export interface FlowExample {
+  /** "<recording>#<trace id>": unique within the flow, stable across runs. */
+  id: string;
+  /**
+   * The file the trace was read from, relative to the verify step's input
+   * root - where an uploaded recording is kept.
+   */
+  recording: string;
+  traceId: string;
+  /** When the root span started, RFC 3339 UTC; absent when the recording has no clock. */
+  recordedAt?: string;
+  /** Root start to the last end the trace shows. */
+  durationMs: number;
+  /** The steps this trace showed, in the order it showed them. */
+  steps: ExampleStep[];
+}
+/**
+ * What one span said about one step. Only an allowlist of attributes is
+ * carried: names, verbs, routes, status codes - never a query text, a header
+ * or a path with an id in it.
+ */
+export interface ExampleStep {
+  step: string;
+  label?: string;
+  durationMs: number;
+  attributes?: Record<string, string>;
+}
+/**
+ * How many recordings showed a step. On a declared step it accompanies the
+ * raised status; on a step no source declares it is why the step is there.
+ */
+export interface StepSeen {
+  traces: number;
 }
 export interface FlowTrigger {
   kind:
@@ -974,6 +1173,8 @@ export interface Step {
   handoff?: FlowHandoff;
   /** Repository call resolved to a concrete store operation after merge. */
   storeAccess?: FlowStoreAccess;
+  /** Recordings that showed this hop; set by a verifier. */
+  seen?: StepSeen;
 }
 export interface HTTPResponse {
   status?: number;
@@ -1029,6 +1230,12 @@ export interface AltBranch {
   steps: FlowNode[];
   /** True when the flow stops here instead of continuing past the alt. */
   terminal?: boolean;
+  /**
+   * Recordings that went this way, on a frame a verifier wrote where the
+   * recordings parted. A branch with no steps and a count is the recordings
+   * that went no further.
+   */
+  seen?: StepSeen;
 }
 export interface Loop {
   type: "loop";
@@ -1272,6 +1479,44 @@ export function allRepos(catalog: Catalog): RepoPin[] {
   return catalog.repos ?? [];
 }
 
+/** Every place a service runs. Absent means none, exactly as with repos. */
+export function allDeployments(catalog: Catalog): Deployment[] {
+  return catalog.deployments ?? [];
+}
+
+/**
+ * Whether a deployment is of this service. The labels decide when the
+ * Application carries them: `service` is the id, and an Application
+ * labelled for one service is not another's however its path reads. Without
+ * labels, the path: the same repository, and the manifests read from inside
+ * the service's directory - or from anywhere in the repository when the
+ * service is the whole of it. An Application that matches nothing is a fact
+ * for the Problems page rather than for a guess.
+ */
+export function deploys(deployment: Deployment, service: Service): boolean {
+  if (deployment.service) return deployment.service === service.id;
+  if (!deployment.repo || deployment.repo !== service.repo) return false;
+  const root = service.path.replace(/^\/+|\/+$/g, "");
+  if (!root) return true;
+  return deployment.path === root || deployment.path.startsWith(`${root}/`);
+}
+
+/**
+ * The environment a reader would say a deployment stands in: the one the
+ * deployer named, else the cluster, else the one word that says neither was
+ * said. Every picture and filter groups by this, so it is decided once.
+ */
+export function environmentOf(deployment: Deployment): string {
+  return deployment.environment || deployment.cluster || "unplaced";
+}
+
+/** Where this service runs, in catalog order: the snapshot's, which is by id. */
+export function deploymentsOf(catalog: Catalog, service: Service): Deployment[] {
+  return allDeployments(catalog).filter((deployment) =>
+    deploys(deployment, service),
+  );
+}
+
 /** Who to ask about a service, without the caller having to know the field is optional. */
 export function ownersOf(service: Service): string[] {
   return service.owners ?? [];