@shortlink-org/portolan 0.2.3 → 0.2.4

package/package.json

@@ -2,7 +2,7 @@
   "name": "@shortlink-org/portolan",
   "description": "Generate a navigable architecture catalog from code and specifications.",
   "private": false,
-  "version": "0.2.3",
+  "version": "0.2.4",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/shortlink-org/portolan#readme",

package/plugins/README.md

@@ -1142,6 +1142,11 @@ live in another estate — would be the wrong end of the trade.
 service declares — the address the broker knows, and each message on it with the
 direction it travels. What it does **not** answer with is events.
 
+A message's `contentType`, or the document's `defaultContentType` when the
+message leaves it out, is kept as the exact declared media type. MessagePack
+media types are additionally normalized to `encoding: msgpack`, so source and
+contract extractors can be compared without depending on one MIME spelling.
+
 That looks like a gap and is a boundary. `Event.id` is
 `<service>.<aggregate>.<Name>`, and an AsyncAPI document knows the message on the
 wire, not the aggregate that raised it. An extractor that guessed would either

package/plugins/extract-python-kafka/README.md

@@ -22,6 +22,12 @@ id, consumer group, key, headers and serializer facts. Authentication values
 are never emitted. Partitions, replication and retention are broker-side facts
 and remain explicitly unknown unless another catalog source declares them.
 
+MessagePack serializers and deserializers declared through `msgpack` or
+`messagepack` calls are normalized to `encoding: "msgpack"` on the affected
+channel message. This includes constructor callbacks and payloads packed
+directly before a publish; Portolan records the wire format without importing
+or executing the codec.
+
 ```json
 {
   "plugin": "python-kafka",

package/plugins/extract-python-kafka/extract.py

@@ -99,7 +99,7 @@ def channel(topic: str, sends: List[kafka.Publish], receives: List[kafka.Subscri
     for item in sends:
         key = (item.message, "send")
         if key not in seen:
-            messages.append(catalog.message(item.message, title(item.message), message_doc(item), "send"))
+            messages.append(catalog.message(item.message, title(item.message), message_doc(item), "send", item.encoding))
             seen.add(key)
     for item in receives:
         # Kafka subscriptions dispatch records, and source often does not prove
@@ -108,7 +108,7 @@ def channel(topic: str, sends: List[kafka.Publish], receives: List[kafka.Subscri
         name = sends[0].message if len({sent.message for sent in sends}) == 1 else "message"
         key = (name, "receive")
         if key not in seen:
-            messages.append(catalog.message(name, title(name), consumer_doc(item), "receive"))
+            messages.append(catalog.message(name, title(name), consumer_doc(item), "receive", item.client.encoding))
             seen.add(key)
     clients = []
     for item in list(sends) + list(receives):

package/plugins/extract-python-kafka/extract_test.py

@@ -1,5 +1,6 @@
 """Framework-neutral Kafka extraction contracts."""
 
+import ast
 import json
 import os
 import sys
@@ -9,6 +10,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 sys.path.insert(1, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "pyplugin"))
 
 from extract import extract  # noqa: E402
+import kafka  # noqa: E402
 from options import Options  # noqa: E402
 from protocol import Builder, Input  # noqa: E402
 
@@ -33,7 +35,7 @@ class PythonKafka(unittest.TestCase):
 
     def test_three_standard_clients_form_message_channels(self):
         channels = {item["address"]: item for item in self.service["channels"]}
-        self.assertEqual(sorted(channels), ["audit.records", "orders.created", "payments.accepted"])
+        self.assertEqual(sorted(channels), ["audit.records", "inventory.snapshots", "orders.created", "payments.accepted"])
         self.assertTrue(all(item["kind"] == "message" for item in channels.values()))
         self.assertEqual(
             [message["direction"] for message in channels["orders.created"]["messages"]],
@@ -50,6 +52,20 @@ class PythonKafka(unittest.TestCase):
         self.assertNotIn("sasl.password", self.contents)
         self.assertNotIn("sasl.username", self.contents)
 
+    def test_messagepack_serializer_and_deserializer_are_machine_readable(self):
+        snapshots = next(item for item in self.service["channels"] if item["address"] == "inventory.snapshots")
+        self.assertEqual([message["encoding"] for message in snapshots["messages"]], ["msgpack", "msgpack"])
+        self.assertIn("value serializer: lambda value: msgpack.packb(value)", snapshots["doc"])
+        self.assertIn("value deserializer: msgpack.unpackb", snapshots["doc"])
+
+    def test_direct_messagepack_call_keeps_the_payload_name(self):
+        call = ast.parse("msgpack.packb(snapshot)", mode="eval").body
+        self.assertEqual(kafka.payload_name(call), "snapshot")
+        self.assertEqual(kafka.payload_encoding(call), "msgpack")
+        packer = ast.parse("msgpack.Packer()", mode="eval").body
+        method = ast.parse("packer.pack(snapshot)", mode="eval").body
+        self.assertEqual(kafka.payload_encoding(method, {"packer": ("expr", packer)}), "msgpack")
+
     def test_publish_and_receive_flows_have_kafka_handoffs_and_source(self):
         steps = [step for flow in self.fragment["flows"] for step in flow["steps"]]
         handoffs = [step["handoff"] for step in steps]

package/plugins/pyplugin/catalog.py

@@ -81,13 +81,24 @@ def channel(address: str, kind: str, title: str, doc: str, messages: List[Dict[s
     return out
 
 
-def message(name: str, title: str, doc: str, direction: str) -> Dict[str, Any]:
+def message(
+    name: str,
+    title: str,
+    doc: str,
+    direction: str,
+    encoding: str = "",
+    content_type: str = "",
+) -> Dict[str, Any]:
     out: Dict[str, Any] = {"name": name}
     if title:
         out["title"] = title
     if doc:
         out["doc"] = doc
     out["direction"] = direction
+    if encoding:
+        out["encoding"] = encoding
+    if content_type:
+        out["contentType"] = content_type
     return out
 
 

package/plugins/pyplugin/kafka.py

@@ -23,6 +23,8 @@ class Spec:
 CONSTRUCTORS = {
     "confluent_kafka.Producer": Spec("confluent-kafka", "producer"),
     "confluent_kafka.Consumer": Spec("confluent-kafka", "consumer"),
+    "confluent_kafka.SerializingProducer": Spec("confluent-kafka", "producer"),
+    "confluent_kafka.DeserializingConsumer": Spec("confluent-kafka", "consumer"),
     "kafka.KafkaProducer": Spec("kafka-python", "producer"),
     "kafka.KafkaConsumer": Spec("kafka-python", "consumer"),
     "aiokafka.AIOKafkaProducer": Spec("aiokafka", "producer"),
@@ -62,6 +64,23 @@ CONFIG_KEYS = {
     "enable_auto_commit": "auto commit",
     "key_serializer": "key serializer",
     "value_serializer": "value serializer",
+    "key_deserializer": "key deserializer",
+    "value_deserializer": "value deserializer",
+    "key.serializer": "key serializer",
+    "value.serializer": "value serializer",
+    "key.deserializer": "key deserializer",
+    "value.deserializer": "value deserializer",
+}
+
+SERDE_KEYS = {
+    "key_serializer",
+    "value_serializer",
+    "key_deserializer",
+    "value_deserializer",
+    "key.serializer",
+    "value.serializer",
+    "key.deserializer",
+    "value.deserializer",
 }
 
 
@@ -73,6 +92,10 @@ class Client:
     source: str = ""
     constructor_topics: List[str] = field(default_factory=list)
 
+    @property
+    def encoding(self) -> str:
+        return encoding_of_text(" ".join(str(self.config.get(key, "")) for key in ("value serializer", "value deserializer")))
+
 
 @dataclass
 class Publish:
@@ -86,6 +109,7 @@ class Publish:
     message_expression: str
     key: str = ""
     headers: str = ""
+    encoding: str = ""
 
     @property
     def line(self) -> str:
@@ -181,6 +205,8 @@ def value(
         for key_node, val_node in zip(node.keys, node.values):
             key = value(project, module, key_node, settings, variables, depth + 1)
             val = value(project, module, val_node, settings, variables, depth + 1)
+            if val is None and isinstance(key, str) and key in SERDE_KEYS:
+                val = serialization_expression(module, val_node, variables)
             if not isinstance(key, str) or val is None:
                 continue
             out[key] = val
@@ -239,14 +265,21 @@ def _config_values(project: Project, module: Module, call: ast.Call, settings: s
         first = value(project, module, call.args[0], settings, variables)
         if isinstance(first, dict):
             raw.update(first)
+        # Callable serializer values are not safe scalar values, but their
+        # syntax is still the evidence needed to identify MessagePack.
+        if isinstance(call.args[0], ast.Dict):
+            for key_node, val_node in zip(call.args[0].keys, call.args[0].values):
+                key = value(project, module, key_node, settings, variables)
+                if isinstance(key, str) and key in SERDE_KEYS and key not in raw:
+                    raw[key] = serialization_expression(module, val_node, variables)
     for kw in call.keywords:
         if not kw.arg:
             continue
         resolved = value(project, module, kw.value, settings, variables)
         if resolved is not None:
             raw[kw.arg] = resolved
-        elif kw.arg in ("key_serializer", "value_serializer"):
-            raw[kw.arg] = expression(kw.value)
+        elif kw.arg in SERDE_KEYS:
+            raw[kw.arg] = serialization_expression(module, kw.value, variables)
     out: Dict[str, Any] = {}
     for key, val in raw.items():
         normalized = CONFIG_KEYS.get(key)
@@ -377,7 +410,7 @@ def payload_name(node: Optional[ast.AST], variables: Optional[Dict[str, Tuple[st
         return node.id
     if isinstance(node, ast.Call):
         last = dotted(node.func).split(".")[-1]
-        if last in ("dumps", "dump", "encode", "serialize", "SerializeToString", "asdict", "dict", "model_dump") and node.args:
+        if last in ("dumps", "dump", "encode", "serialize", "SerializeToString", "asdict", "dict", "model_dump", "pack", "packb") and node.args:
             return payload_name(node.args[0], variables, depth + 1)
         return last or "message"
     if isinstance(node, ast.Attribute):
@@ -387,6 +420,43 @@ def payload_name(node: Optional[ast.AST], variables: Optional[Dict[str, Tuple[st
     return "message"
 
 
+def encoding_of_text(text: str) -> str:
+    lowered = text.lower()
+    if "msgpack" in lowered or "messagepack" in lowered:
+        return "msgpack"
+    return ""
+
+
+def serialization_expression(module: Optional[Module], node: Optional[ast.AST], variables: Optional[Dict[str, Tuple[str, object]]] = None) -> str:
+    if node is None:
+        return ""
+    parts = [expression(node)]
+    if module is not None:
+        parts.append(external_name(module, dotted(node.func) if isinstance(node, ast.Call) else dotted(node)))
+    owner = node.func.value if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) else (node.value if isinstance(node, ast.Attribute) else None)
+    if isinstance(owner, ast.Name):
+        bound = (variables or {}).get(owner.id)
+        if bound is not None and bound[0] == "expr" and isinstance(bound[1], ast.AST):
+            parts.append(expression(bound[1]))
+    return " ".join(filter(None, parts))
+
+
+def payload_encoding(
+    node: Optional[ast.AST],
+    variables: Optional[Dict[str, Tuple[str, object]]] = None,
+    depth: int = 0,
+    module: Optional[Module] = None,
+) -> str:
+    if node is None or depth > 6:
+        return ""
+    variables = variables or {}
+    if isinstance(node, ast.Name):
+        bound = variables.get(node.id)
+        if bound is not None and bound[0] == "expr" and isinstance(bound[1], ast.AST):
+            return payload_encoding(bound[1], variables, depth + 1, module)
+    return encoding_of_text(serialization_expression(module, node, variables))
+
+
 def _text(node: Optional[ast.AST]) -> str:
     text = expression(node)
     return text if len(text) <= 100 else text[:97] + "..."
@@ -541,6 +611,7 @@ class Scanner:
                 _text(payload),
                 _text(keyword(call, "key")),
                 _text(keyword(call, "headers")),
+                payload_encoding(payload, env, module=module) or client.encoding,
             )
         )
 

package/scripts/gen-likec4.mjs

@@ -590,10 +590,11 @@ function containerPredicates(pairs, carried, indent) {
  * in a `break` frame, which is what a sequence diagram calls a branch that
  * leaves the flow rather than rejoining it.
  */
-// --- what comes back from a call (mirrors src/flow/answers.ts) -------------
-// Standalone calls keep the contract answer on the request label. Composition
-// turns a proven synchronous return into an explicit response step, so the
-// request then keeps only its own label and the return gets a dashed arrow.
+// --- request and response edges (mirrors src/flow/answers.ts) --------------
+// A unary RPC is two messages, not one long edge label. When composition has
+// already materialised a response step, that step is the return. Otherwise we
+// draw the contract response: immediately for a nested call, and at the end of
+// the flow for the actor request that opened it.
 const methodOf = new Map();
 const serviceById = new Map();
 for (const context of catalog.contexts) {
@@ -615,29 +616,43 @@ for (const external of catalog.externals ?? []) {
   }
 }
 
-function answerOf(step) {
-  if (step.kind !== "rpc") return "";
-  if (step.ref) return methodOf.get(step.ref)?.response ?? "";
+function contractOf(step) {
+  if (step.kind !== "rpc") return null;
+  if (step.ref) return methodOf.get(step.ref) ?? null;
   const service = serviceById.get(step.to);
-  if (!service || !step.label) return "";
+  if (!service || !step.label) return null;
   for (const provided of service.provides) {
     const found = provided.methods.find((m) => m.name === step.label);
-    if (found) return found.response ?? "";
+    if (found) return found;
   }
-  return "";
+  return null;
+}
+
+function emitSyntheticResponse(out, indent, node, response) {
+  out.push(
+    `${indent}${participantRef(node.to)} -> ${participantRef(node.from)} ${q(response)} {`,
+  );
+  out.push(
+    `${indent}  color ${node.status}  line dashed  head ${KIND_HEAD.response}`,
+  );
+  out.push(`${indent}}`);
 }
 
-function emitSteps(nodes, out, indent, replied) {
+function emitSteps(nodes, out, indent, replied, deferredResponseId) {
   for (const node of nodes) {
     if (node.type === "step") {
-      const answer = replied.has(node.id) ? "" : answerOf(node);
+      const contract = contractOf(node);
+      const request = contract?.request ?? "";
+      const response = replied.has(node.id) ? "" : (contract?.response ?? "");
       const storeLabel =
         node.storeAccess?.operation && node.storeAccess?.keyspace
           ? `${node.storeAccess.operation.toUpperCase()} ${node.storeAccess.keyspace}`
           : "";
       const label =
-        (storeLabel || node.label || node.ref || node.kind) +
-        (answer ? ` → ${answer}` : "");
+        storeLabel ||
+        (node.kind === "rpc" && request
+          ? request
+          : node.label || node.ref || node.kind);
       const attrs = [
         `color ${node.http?.outcome === "error" ? "response_error" : node.status}`,
         `line ${node.kind === "response" ? "dashed" : "solid"}`,
@@ -656,18 +671,21 @@ function emitSteps(nodes, out, indent, replied) {
       if (notes.length > 0)
         out.push(`${indent}  notes ${q(notes.join(" — "))}`);
       out.push(`${indent}}`);
+      if (response && node.id !== deferredResponseId) {
+        emitSyntheticResponse(out, indent, node, response);
+      }
       continue;
     }
     if (node.type === "parallel") {
       out.push(`${indent}par ${node.title ? `${q(node.title)} ` : ""}{`);
       for (const branch of node.branches)
-        emitSteps(branch, out, `${indent}  `, replied);
+        emitSteps(branch, out, `${indent}  `, replied, deferredResponseId);
       out.push(`${indent}}`);
       continue;
     }
     if (node.type === "loop") {
       out.push(`${indent}loop ${q(node.title)} {`);
-      emitSteps(node.steps, out, `${indent}  `, replied);
+      emitSteps(node.steps, out, `${indent}  `, replied, deferredResponseId);
       out.push(`${indent}}`);
       continue;
     }
@@ -678,10 +696,22 @@ function emitSteps(nodes, out, indent, replied) {
         out.push(`${indent}  ${keyword} ${q(branch.title)} {`);
         if (branch.terminal) {
           out.push(`${indent}    break 'ends the flow' {`);
-          emitSteps(branch.steps, out, `${indent}      `, replied);
+          emitSteps(
+            branch.steps,
+            out,
+            `${indent}      `,
+            replied,
+            deferredResponseId,
+          );
           out.push(`${indent}    }`);
         } else {
-          emitSteps(branch.steps, out, `${indent}    `, replied);
+          emitSteps(
+            branch.steps,
+            out,
+            `${indent}    `,
+            replied,
+            deferredResponseId,
+          );
         }
         out.push(`${indent}  }`);
       });
@@ -961,16 +991,34 @@ views.push("");
 for (const flow of catalog.flows) {
   const contexts = new Map(flow.participants.map((p) => [p.id, p.context]));
   const contextOf = (id) => contexts.get(id) ?? null;
+  const actorIds = new Set(
+    flow.participants.filter((p) => p.kind === "actor").map((p) => p.id),
+  );
   const replied = new Set();
   walkFlowSteps(flow.steps, (step) => {
     if (step.kind === "response" && step.replyTo) replied.add(step.replyTo);
   });
+  let deferredResponse = null;
+  walkFlowSteps(flow.steps, (step) => {
+    if (deferredResponse || step.kind !== "rpc" || !actorIds.has(step.from))
+      return;
+    const response = replied.has(step.id) ? "" : (contractOf(step)?.response ?? "");
+    if (response) deferredResponse = { step, response };
+  });
 
   views.push(`  dynamic view ${flowViewId(flow)} {`);
   views.push(`    title ${q(flow.name)}`);
   views.push(`    description ${q(flow.summary)}`);
   const body = [];
-  emitSteps(flow.steps, body, "    ", replied);
+  emitSteps(flow.steps, body, "    ", replied, deferredResponse?.step.id);
+  if (deferredResponse) {
+    emitSyntheticResponse(
+      body,
+      "    ",
+      deferredResponse.step,
+      deferredResponse.response,
+    );
+  }
   views.push(...body);
   views.push("  }");
   views.push("");
@@ -979,7 +1027,17 @@ for (const flow of catalog.flows) {
   views.push(`  dynamic view ${flowCrossViewId(flow)} {`);
   views.push(`    title ${q(`${flow.name} — crossings only`)}`);
   const crossBody = [];
-  emitSteps(cross, crossBody, "    ", replied);
+  const crossStepIds = new Set();
+  walkFlowSteps(cross, (step) => crossStepIds.add(step.id));
+  emitSteps(cross, crossBody, "    ", replied, deferredResponse?.step.id);
+  if (deferredResponse && crossStepIds.has(deferredResponse.step.id)) {
+    emitSyntheticResponse(
+      crossBody,
+      "    ",
+      deferredResponse.step,
+      deferredResponse.response,
+    );
+  }
   if (crossBody.length === 0) {
     // A flow with no crossing at all still needs a renderable view.
     const first = flow.participants[0];

package/scripts/gen-likec4.test.mjs

@@ -164,11 +164,34 @@ describe("the LikeC4 generator", () => {
             },
           ],
         },
+        {
+          id: "flow.get-book-contract",
+          slug: "get-book-contract",
+          name: "Get book contract",
+          summary: "",
+          owner: "demo",
+          participants: [
+            { id: "demo.api", kind: "service", context: "demo" },
+            { id: "demo.book", kind: "service", context: "demo" },
+          ],
+          steps: [
+            {
+              type: "step",
+              id: "request",
+              from: "demo.api",
+              to: "demo.book",
+              kind: "rpc",
+              ref: "book.v1.Book/Get",
+              label: "Get",
+              status: "declared",
+            },
+          ],
+        },
       ],
     });
 
     expect(views).toContain(
-      "demo.api -> demo.book 'Get' {\n      color declared  line solid  head normal",
+      "demo.api -> demo.book 'GetRequest' {\n      color declared  line solid  head normal",
     );
     expect(views).toContain(
       "demo.book -> demo.api 'GetResponse' {\n      color declared  line dashed  head normal",
@@ -177,7 +200,7 @@ describe("the LikeC4 generator", () => {
       "demo.book -> demo.api '500 · Error' {\n      color response_error  line dashed  head normal",
     );
     expect(spec).toContain("color response_error #b7646b");
-    expect(views).not.toContain("Get → GetResponse");
+    expect(views).not.toContain("GetRequest → GetResponse");
   });
 
   it("treats dots in a root participant id as data, not containment", () => {

package/src/app/Breadcrumbs.test.ts

@@ -31,6 +31,10 @@ describe("crumbsFor", () => {
       { label: "settings", to: "/settings" },
       { label: "delivery", to: "/settings/delivery" },
     ]);
+    expect(crumbsFor("/settings/integrations")).toEqual([
+      { label: "settings", to: "/settings" },
+      { label: "integrations", to: "/settings/integrations" },
+    ]);
   });
 
   it("reads 'data' as a literal, not as an aggregate", () => {

package/src/app/Breadcrumbs.tsx

@@ -51,6 +51,7 @@ export function crumbsFor(pathname: string): Crumb[] {
       projects: "projects",
       pipeline: "pipeline",
       delivery: "delivery",
+      integrations: "integrations",
       preferences: "preferences",
     };
     return [

package/src/catalog-model.ts

@@ -627,6 +627,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;
@@ -771,6 +775,23 @@ export interface Table {
   /** The domain object this table holds: an aggregate id, and optionally a block id. */
   persists?: { aggregate?: string; block?: string };
   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 {
@@ -893,7 +914,7 @@ export interface Step {
   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) {