@shortlink-org/portolan 0.2.3 → 0.3.0

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/plugins/pyplugin/protocol.py

@@ -17,12 +17,10 @@ from typing import Any, Dict, List
 
 @dataclass
 class Input:
-    """Where the source is, and the stamp the host put on this run."""
+    """Where the source is."""
 
     root: str = ""
     output: str = ""
-    commit: str = ""
-    generated_at: str = ""
 
     @staticmethod
     def of(raw: Any) -> "Input":
@@ -30,8 +28,6 @@ class Input:
         return Input(
             root=raw.get("root", ""),
             output=raw.get("output", ""),
-            commit=raw.get("commit", ""),
-            generated_at=raw.get("generatedAt", ""),
         )
 
 

package/portolan.json

@@ -167,8 +167,9 @@
     },
     {
       "name": "http-clients",
-      "wasm": {
-        "url": "file://plugins/portolan-go.wasm"
+      "process": {
+        "command": "go",
+        "args": ["run", "./plugins/cmd/portolan-http-clients"]
       }
     },
     {

package/schema/portolan.schema.json

@@ -44,6 +44,14 @@
       },
       "description": "The source projects that make up the estate. A project gives repeated pipeline inputs one name for the generated site's Settings page; estate-wide inputs such as flows need no project."
     },
+    "warningPolicies": {
+      "type": "array",
+      "maxItems": 100,
+      "items": {
+        "$ref": "#/$defs/warningPolicy"
+      },
+      "description": "CEL policies for reviewed extraction limitations. Expressions are type-checked when the manifest is read and suppression always requires a reason."
+    },
     "plugins": {
       "type": "array",
       "items": {
@@ -795,6 +803,32 @@
     }
   },
   "$defs": {
+    "warningPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "when",
+        "action",
+        "reason"
+      ],
+      "properties": {
+        "when": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1000,
+          "description": "Boolean CEL expression over plugin, rule, severity, project, phase, ref, message and count."
+        },
+        "action": {
+          "const": "suppress",
+          "description": "Suppress matching diagnostics from the active view while retaining them in the report."
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Why this limitation is consciously accepted."
+        }
+      }
+    },
     "catalogProfile": {
       "type": "object",
       "additionalProperties": false,

package/scripts/README.md

@@ -1,8 +1,8 @@
 # Host
 
 The side of portolan that runs. `npm run gen` reads the manifest, runs every
-plugin it names, stamps and writes what comes back, merges the sources into
-one estate and validates the union. Nothing here draws anything.
+plugin it names, writes what comes back, merges the sources into one estate
+and validates the union. Nothing here draws anything.
 
 ## What it does
 
@@ -10,21 +10,25 @@ one estate and validates the union. Nothing here draws anything.
   the schema `npm run schema` composes out of what every declared plugin says
   it can be told.
 - Runs three phases in order, extract, verify, generate, and hands each
-  plugin one JSON message: the input root, output directory and stamp for an
+  plugin one JSON message: the input root and output directory for an
   extractor, the merged catalog for a verifier or a generator, the step's
   options unread. The output path lets a fragment point at a companion file
   returned in the same response without letting the plugin write it itself.
-- Stamps a fragment from the last commit that touched its input, never from a
-  clock, so a committed fragment changes exactly when its subject does
-  (portolan.0002).
+- Writes no provenance into a fragment. When a source last changed, and in
+  which commit, is read from the history of the checkout wherever the catalog
+  is read - here, by the LikeC4 generator, by the architecture diff and by
+  the site as Vite builds it - so a fragment is content and nothing else, and
+  regenerating from the same sources changes no byte (portolan.0010).
 - Writes the files a plugin named, refuses a name that climbs out of the
   step's output directory, keeps a listing per step of what it wrote, and
   deletes what stopped being generated (portolan.0001).
 - Merges every source the manifest's globs find and validates the union with
   the code the site runs: `src/merge.ts`, `src/catalog.ts`, `src/enrich.ts`.
 - In `--check` mode writes nothing and fails on the first file that differs
-  from disk. Either way it leaves `.portolan/build-report.json` for the
-  Settings page.
+  from disk, saying where the file first differs and what changed among the
+  step's inputs since its output was last committed - the history is the
+  record of the last generation, so nothing else has to be. Either way it
+  leaves `.portolan/build-report.json` for the Settings page.
 
 ## What it does not do
 
@@ -47,7 +51,9 @@ one estate and validates the union. Nothing here draws anything.
   that report put on the pull request as one comment kept current;
   `forge-release.mjs`, the same report as one section of a release's notes;
   `forge.mjs`, what those two share - which forge the CI is, and how to talk
-  to it; `vendor-lock.mjs`,
-  the commit a fetched copy is of; `site-docs.mjs`, generated documentation
-  put into the built site; `local-api.mjs`, what the dev server answers the
-  site with.
+  to it; `history.mjs`, what the checkout's history says about every file,
+  for a plugin that asks and for the provenance of every source;
+  `provenance.mjs`, that provenance handed to the site as one virtual module;
+  `output-diff.mjs`, where a generated file first differs from what the
+  generator produces; `site-docs.mjs`, generated documentation put into the
+  built site; `local-api.mjs`, what the dev server answers the site with.

package/scripts/catalog-sources.mjs

@@ -14,6 +14,7 @@ import { validateCatalog } from "../src/catalog.ts";
 import { filterCatalogForProfile } from "../src/catalog-profile.ts";
 import { enrichCatalog } from "../src/enrich.ts";
 import { mergeCatalogs } from "../src/merge.ts";
+import { stampsFor } from "./history.mjs";
 import { readManifest } from "./manifest.mjs";
 
 /**
@@ -48,10 +49,15 @@ export async function loadCatalog(manifestPath = "portolan.json", { exclude = []
     );
   }
 
+  // A source is dated by the history, not by itself (portolan.0010): the
+  // commit that last changed the file, and its date, read here and never
+  // written into the file.
+  const stamps = stampsFor(process.cwd(), paths);
   const merged = mergeCatalogs(
     paths.map((path) => ({
       path,
       catalog: JSON.parse(readFileSync(path, "utf8")),
+      stamp: stamps.get(path),
     })),
   );
   if (paths.length === 0) {

package/scripts/delivery-presets.mjs

@@ -23,7 +23,10 @@ const GITLAB_START = "# >>> Portolan delivery preset >>>";
 const GITLAB_END = "# <<< Portolan delivery preset <<<";
 const PROVIDERS = new Set(["github", "gitlab"]);
 const FEATURE_IDS = ["check", "diff", "sarif", "pages"];
-const DEFAULT_FEATURES = ["check", "pages"];
+const DEFAULT_FEATURES = {
+  github: ["check", "pages"],
+  gitlab: ["pages"],
+};
 const FEATURE_DETAILS = {
   check: {
     label: "Architecture check",
@@ -225,7 +228,9 @@ ${upload}`;
 
 function gitlabCheck() {
   return `"portolan:check":
-  stage: .pre
+  stage: test
+  tags:
+    - runner-type:docker
   image:
     name: ghcr.io/shortlink-org/portolan:${VERSION}
     entrypoint: [""]
@@ -242,7 +247,9 @@ function gitlabCheck() {
 function gitlabDiff({ pages }) {
   const site = pages ? ' --site "$CI_PAGES_URL"' : "";
   return `"portolan:review":
-  stage: .pre
+  stage: test
+  tags:
+    - runner-type:docker
   image:
     name: ghcr.io/shortlink-org/portolan:${VERSION}
     entrypoint: [""]
@@ -259,8 +266,10 @@ function gitlabDiff({ pages }) {
 }
 
 function gitlabPages() {
-  return `"portolan:pages":
-  stage: .post
+  return `pages:
+  stage: deploy
+  tags:
+    - runner-type:docker
   image:
     name: ghcr.io/shortlink-org/portolan:${VERSION}
     entrypoint: [""]
@@ -268,9 +277,10 @@ function gitlabPages() {
     GIT_DEPTH: "0"
   script:
     - BASE_PATH="$(node -p 'new URL(process.env.CI_PAGES_URL).pathname.replace(/\\/?$/, "/") || "/"')"
-    - portolan build --output dist --base "$BASE_PATH"
-  pages:
-    publish: dist
+    - portolan build --output public --base "$BASE_PATH"
+  artifacts:
+    paths:
+      - public
   rules:
     - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
 `;
@@ -299,7 +309,7 @@ function mergeGitlab(existing, features) {
       .replace(/^\n+|\n+$/g, "");
     return { content: content ? `${content}\n` : "" };
   }
-  if (/^[ \t]*["']?portolan:(?:check|review|pages)["']?\s*:/m.test(existing)) {
+  if (/^(?:["']?portolan:(?:check|review|pages)["']?|["']?pages["']?)\s*:/m.test(existing)) {
     return { conflict: "This pipeline already declares a Portolan job outside the managed region." };
   }
   const block = gitlabBlock(features);
@@ -421,14 +431,14 @@ function installedFeatures(workspace, provider) {
   );
   if (/^[ \t]*["']?portolan:check["']?\s*:/m.test(managed)) selected.add("check");
   if (/^[ \t]*["']?portolan:review["']?\s*:/m.test(managed)) selected.add("diff");
-  if (/^[ \t]*["']?portolan:pages["']?\s*:/m.test(managed)) selected.add("pages");
+  if (/^(?:["']?portolan:pages["']?|["']?pages["']?)\s*:/m.test(managed)) selected.add("pages");
   return selected;
 }
 
 function selectedFeatures(workspace, request, provider) {
   const installed = request.features == null ? installedFeatures(workspace, provider) : null;
   const raw = request.features == null
-    ? installed.size > 0 ? [...installed] : DEFAULT_FEATURES
+    ? installed.size > 0 ? [...installed] : DEFAULT_FEATURES[provider]
     : Array.isArray(request.features)
       ? request.features
       : String(request.features).split(",").filter(Boolean);

package/scripts/diff.mjs

@@ -157,8 +157,12 @@ function catalogAt(ref) {
     throw new Error(ref + " holds no catalog sources matching " + JSON.stringify(manifest.sources));
   }
 
+  // The base is one commit, and a commit is its own provenance: every source
+  // there is dated by it (portolan.0010), whatever an older fragment says.
+  const [commit = "", generatedAt = ""] = git(["log", "-1", "--format=%h %cI", ref]).split(" ");
+  const stamp = { commit, generatedAt };
   const merged = mergeCatalogs(
-    paths.map((path) => ({ path, catalog: JSON.parse(git(["show", ref + ":" + path])) })),
+    paths.map((path) => ({ path, catalog: JSON.parse(git(["show", ref + ":" + path])), stamp })),
   );
 
   // Enriched before it is compared, exactly as the app and the generators see

package/scripts/django-aggregates.test.mjs

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { djangoAggregateProposals, saveDjangoAggregates } from "./local-api.mjs";
+
+const roots = [];
+afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+function fixture() {
+  const root = mkdtempSync(join(tmpdir(), "portolan-aggregates-")); roots.push(root);
+  const manifest = { sources: ["data/*.json"], extract: ["one", "two"].map((name) => ({ plugin: "django-domain", in: name, out: `data/${name}`, options: { context: name, service: name, aggregates: { existing: "Existing" }, apps: ["billing.records"] } })) };
+  const text = JSON.stringify(manifest);
+  writeFileSync(join(root, "portolan.json"), text);
+  const message = `billing/records: no model called Records, and 2 models to choose from: name the root in the aggregates option; aggregate candidates: ${JSON.stringify({ app: "billing.records", models: [{ name: "Entry", path: "billing/records/models.py", line: 1 }, { name: "Audit", path: "billing/records/models.py", line: 10 }] })}`;
+  const report = { status: "ok", manifestSha256: createHash("sha256").update(text).digest("hex"), steps: manifest.extract.map((step) => ({ phase: "extract", plugin: step.plugin, input: step.in, output: step.out, warnings: [message] })) };
+  mkdirSync(join(root, ".portolan")); writeFileSync(join(root, ".portolan/build-report.json"), JSON.stringify(report));
+  return { root, manifest, report };
+}
+
+describe("saving Django aggregate roots", () => {
+  it("targets the precise step and dotted app, preserving unrelated options", () => {
+    const { root, manifest } = fixture();
+    const proposals = djangoAggregateProposals(root);
+    expect(proposals.stale).toBe(false);
+    expect(proposals.proposals).toHaveLength(2);
+    saveDjangoAggregates(root, { revision: proposals.revision, selections: [{ id: "1:billing.records", model: "Entry" }] });
+    const saved = JSON.parse(readFileSync(join(root, "portolan.json"), "utf8"));
+    expect(saved.extract[0]).toEqual(manifest.extract[0]);
+    expect(saved.extract[1].options).toEqual({ ...manifest.extract[1].options, aggregates: { existing: "Existing", "billing.records": "Entry" } });
+    expect(djangoAggregateProposals(root).stale).toBe(true);
+  });
+
+  it("saves a batch atomically and rejects forged, duplicate, or stale choices", () => {
+    const { root } = fixture();
+    const { revision } = djangoAggregateProposals(root);
+    const original = readFileSync(join(root, "portolan.json"), "utf8");
+    for (const selections of [[], [{ id: "0:billing.records", model: "Proxy" }], [{ id: "no-such-step", model: "Entry" }], [{ id: "0:billing.records", model: "Entry" }, { id: "1:billing.records", model: "Invalid" }], [{ id: "0:billing.records", model: "Entry" }, { id: "0:billing.records", model: "Audit" }]]) {
+      expect(() => saveDjangoAggregates(root, { revision, selections })).toThrow();
+      expect(readFileSync(join(root, "portolan.json"), "utf8")).toBe(original);
+    }
+    const selections = [{ id: "0:billing.records", model: "Entry" }, { id: "1:billing.records", model: "Audit" }];
+    expect(() => saveDjangoAggregates(root, { revision: "old", selections })).toThrow(/changed/);
+    expect(saveDjangoAggregates(root, { revision, selections })).toEqual({ saved: 2 });
+    expect(() => saveDjangoAggregates(root, { revision, selections })).toThrow(/changed/);
+  });
+
+  it("requires fresh report evidence and refuses ambiguous step bindings", () => {
+    const { root, manifest, report } = fixture();
+    manifest.extract.push(manifest.extract[0]);
+    writeFileSync(join(root, "portolan.json"), JSON.stringify(manifest));
+    expect(djangoAggregateProposals(root).proposals.map((p) => p.id)).toEqual(["1:billing.records"]);
+    expect(djangoAggregateProposals(root).stale).toBe(true);
+    report.steps = [];
+    writeFileSync(join(root, ".portolan/build-report.json"), JSON.stringify(report));
+    expect(djangoAggregateProposals(root).proposals).toEqual([]);
+  });
+});

package/scripts/gen-likec4.mjs

@@ -278,7 +278,7 @@ for (const context of catalog.contexts) {
     model.push(`      style { color ${contextColorName(context.id)} }`);
     for (const aggregate of service.aggregates) {
       model.push(
-        `      ${safeId(aggregate.slug)} = aggregate ${q(aggregate.name)} {`,
+        `      ${safeId(aggregate.slug)} = aggregate ${q(aggregate.kind === "model-group" ? `${aggregate.name} (model group)` : aggregate.name)} {`,
       );
       for (const event of aggregate.events) {
         const latest = event.versions[event.versions.length - 1];
@@ -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];