@specific.dev/spectest 0.48.0 → 0.50.0

package/src/daemon.ts

@@ -112,17 +112,22 @@ import {
 } from "./harness/methods.js";
 import type { Mobile, MobileApp } from "./mobile.js";
 import { openTerminal } from "./terminal.js";
+import { readAnnotation, type RenderAnnotation } from "./annotate.js";
 import {
+  pauseRecording,
+  recordEmail,
   recordEnv,
   recordExec,
   recordFake,
   recordHttp,
+  recordStep,
   recordTerminal,
   recordWait,
   reserveEvent,
   recorderEventCount,
   recorderMarkChildren,
   recorderTruncate,
+  resumeRecording,
   startRecording,
   stopRecording,
   truncateUtf8,
@@ -1111,17 +1116,141 @@ async function prepareServiceImage(
   return buildServiceImage(svc.name, image, tag);
 }
 
+/**
+ * What the folded CA step prints when it could not write the trust store
+ * at all — the one outcome that still needs {@link ensureCaTrustedImage},
+ * which can take root for the write.
+ *
+ * The step assembles this prefix from a shell variable so that the marker
+ * appears ONLY in the step's output. BuildKit echoes each instruction into
+ * the same log verbatim, so a marker written literally in the RUN would
+ * match on every build whether or not the step ever printed it.
+ */
+const CA_FOLD_UNWRITABLE = "[spectest-ca] trust store not writable";
+
+/**
+ * The CA-trust steps as a suffix appended to a dockerfile service's OWN
+ * Dockerfile, so one build produces the finished image instead of a build
+ * plus a derivative rebuild ({@link ensureCaTrustedImage}) per service.
+ * Returns null when there is no CA to layer, or when the PEM can't be
+ * quoted — the caller then falls back to the derivative build.
+ *
+ * The PEM is written INLINE rather than `COPY`d: the build context is
+ * `/workspace` under a per-service ignore file that the project itself
+ * contributes to (a `**` line with re-includes is the common idiom), and
+ * a context path we don't control is a context path that can be excluded.
+ * printf needs nothing but a shell.
+ *
+ * Two rules make this safe to bolt onto user code. It must never fail the
+ * build — every branch ends in an echo, so the RUN exits 0 whatever the
+ * image lacks — and it must never change the image, beyond the trust
+ * store: notably no `USER root`, since we cannot know statically what
+ * user to hand back. An image that declares a non-root user therefore
+ * fails to write and is finished by the derivative build, which inspects
+ * the built image and can escalate properly.
+ */
+async function caTrustSuffix(): Promise<string | null> {
+  if (!existsSync(CA_PATH)) return null;
+  const pem = (await fs.readFile(CA_PATH, "utf8")).trim();
+  // A quote in the PEM would break out of the shell quoting below. PEM is
+  // base64 and dashes, so this is a guard, not a case we expect.
+  if (!pem || pem.includes("'")) return null;
+  const args = pem
+    .split("\n")
+    .map((l) => `'${l.trimEnd()}'`)
+    .join(" ");
+  const dst = "/usr/local/share/ca-certificates/spectest-ca.crt";
+  return `
+# spectest: trust the environment's root CA. Appended by the harness —
+# not part of the project's Dockerfile.
+RUN P='[spectest-ca]'; \\
+    mkdir -p /usr/local/share/ca-certificates 2>/dev/null; \\
+    if printf '%s\\n' ${args} > ${dst} 2>/dev/null; then \\
+      if command -v update-ca-certificates >/dev/null 2>&1 && update-ca-certificates >/dev/null 2>&1; then \\
+        echo "$P trusted via update-ca-certificates"; \\
+      elif command -v update-ca-trust >/dev/null 2>&1 && cp ${dst} /etc/pki/ca-trust/source/anchors/spectest-ca.crt && update-ca-trust extract >/dev/null 2>&1; then \\
+        echo "$P trusted via update-ca-trust"; \\
+      else \\
+        echo "$P no system CA trust tool in image; env-var trust only"; \\
+      fi; \\
+    else \\
+      echo "$P trust store not writable by this image's user"; \\
+    fi
+`;
+}
+
+/**
+ * Build a dockerfile service's image.
+ *
+ * The CA-trust layer is folded into THIS build when it can be (see
+ * {@link caTrustSuffix}), so a service costs one image build and one
+ * export rather than two. The derivative build stays as the fallback for
+ * everything the folded form can't serve: an image with no shell to run
+ * the step (distroless, scratch — the appended RUN can't execute, so the
+ * build fails and we rebuild the project's Dockerfile untouched), and an
+ * image that declares a non-root user (the step runs as that user and
+ * can't write the trust store).
+ */
 async function buildServiceImage(
   name: string,
   image: { content: string; exclude?: readonly string[] },
   tag: string,
 ): Promise<{ tag: string; buildSteps?: BuildStep[] }> {
+  const suffix = await caTrustSuffix();
+  let attempt = await runServiceBuild(name, image, tag, suffix);
+  if (!attempt.ok && suffix) {
+    // Our step must not be able to break a project's build.
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[ca-trust] folded CA step could not run in ${name}'s image; rebuilding without it`,
+    );
+    attempt = await runServiceBuild(name, image, tag, null);
+  }
+  if (!attempt.ok) {
+    progressService(name, { status: "failed" });
+    throw new Error(`docker build for ${name} failed:\n${attempt.log}`);
+  }
+  // The derivative build is still needed for the one thing the folded step
+  // cannot do: write the trust store of an image that does not run as
+  // root. That is decided on the IMAGE, not on the build log — a CACHED
+  // layer prints nothing, so a log-only check would quietly stop
+  // re-applying the moment BuildKit had the layer. The log covers the
+  // rarer case of a root image whose /etc is read-only.
+  //
+  // An image with no trust tool at all needs nothing further: the
+  // derivative build would reach the same dead end, and `runContainer`'s
+  // env vars are the fallback either way.
+  const needsDerivative =
+    !attempt.folded ||
+    attempt.log.includes(CA_FOLD_UNWRITABLE) ||
+    !(await imageRunsAsRoot(tag));
+  if (needsDerivative) await ensureCaTrustedImage(name, tag);
+  return { tag, buildSteps: attempt.buildSteps };
+}
+
+/** Whether `tag`'s declared `USER` is root (or unset, which means root). */
+async function imageRunsAsRoot(tag: string): Promise<boolean> {
+  const user = (
+    await docker(["image", "inspect", "--format", "{{.Config.User}}", tag], 60_000)
+  ).stdout.trim();
+  return user === "" || user === "root" || user === "0";
+}
+
+async function runServiceBuild(
+  name: string,
+  image: { content: string; exclude?: readonly string[] },
+  tag: string,
+  caSuffix: string | null,
+): Promise<{ ok: boolean; folded: boolean; log: string; buildSteps?: BuildStep[] }> {
   let buildSteps: BuildStep[] | undefined;
   {
+    const content = caSuffix
+      ? `${image.content.replace(/\n*$/, "\n")}${caSuffix}`
+      : image.content;
     const dfDir = path.join(WORKSPACE, ".spectest", "services", name);
     await fs.mkdir(dfDir, { recursive: true });
     const dfPath = path.join(dfDir, "Dockerfile");
-    await fs.writeFile(dfPath, image.content);
+    await fs.writeFile(dfPath, content);
     // Per-service ignore: BuildKit resolves `<Dockerfile>.dockerignore`
     // (next to the Dockerfile) in preference to the context root's
     // `.dockerignore`, so this build sees the defaults, the project's own
@@ -1181,11 +1310,11 @@ async function buildServiceImage(
         });
       }
     });
+    const log = `${build.stderr.trim()}\n${build.stdout.trim()}`;
     if (build.code !== 0) {
-      progressService(name, { status: "failed" });
-      throw new Error(
-        `docker build for ${name} failed:\n${build.stderr.trim()}\n${build.stdout.trim()}`,
-      );
+      // The caller decides whether this is fatal: a failure with the CA
+      // step appended is retried without it before anyone hears about it.
+      return { ok: false, folded: caSuffix !== null, log };
     }
     if (useBuildKit) {
       // Keep only the slowest dozen steps ≥1s — enough to profile, small
@@ -1194,14 +1323,8 @@ async function buildServiceImage(
         .filter((s) => s.secs >= 1)
         .slice(0, 12);
     }
+    return { ok: true, folded: caSuffix !== null, log, buildSteps };
   }
-  // Layer the spectest CA into the image's system trust store so apps
-  // that read the system bundle (Go, Java, CLIs that don't honour the
-  // SSL_CERT_FILE env vars) accept HTTPS to fakes. Best-effort: images
-  // without `update-ca-certificates` / `update-ca-trust` (distroless,
-  // scratch) fall through to the env-var path that `runContainer` sets.
-  await ensureCaTrustedImage(name, tag);
-  return { tag, buildSteps };
 }
 
 /**
@@ -2728,14 +2851,27 @@ function invokeFakeHelper(
   const args = callArgs.map((a) => deepUnwrap(a));
   const safeArgs = args.map((a) => safeSerialize(a));
   const recordResult = (value: unknown): unknown => {
+    // A helper may box its return in a render annotation
+    // (`annotate(v, "email", …)`). The box never reaches the test, and it
+    // never replaces the step either: the call is recorded as the ordinary
+    // `fake` event it is, and the annotation rides *under* it as a child
+    // event (`parentSeq`), which the dashboard folds into the fake step's
+    // detail panel. So the timeline reads the same as any other helper
+    // call, with the richer view one click in.
+    const annotated = readAnnotation(value);
+    const raw = annotated ? annotated.value : value;
+    const durationMs = Date.now() - t;
     const seq = recordFake({
       fake: fakeName,
       member,
       args: safeArgs,
-      result: safeSerialize(value),
-      durationMs: Date.now() - t,
+      result: safeSerialize(raw),
+      durationMs,
     }, resv);
-    return wrap(value, seq);
+    if (annotated && seq !== undefined) {
+      recordAnnotationChild(fakeName, member, annotated.annotation, durationMs, seq);
+    }
+    return wrap(raw, seq);
   };
   const recordError = (err: unknown): void => {
     recordFake({
@@ -2747,22 +2883,93 @@ function invokeFakeHelper(
     }, resv);
   };
 
+  // A helper call is ONE step. Whatever the fake does inside it — a fetch to
+  // deliver a webhook, a call to its own API — is the fake's plumbing, not
+  // something the test did, and it would otherwise land on the timeline as
+  // an `http` step the test never made. The built-in `email()` helpers
+  // already pause around their internal polls by hand for exactly this
+  // reason (`components/email.ts`); doing it here gives every user-authored
+  // fake the same contract without having to know about it.
+  //
+  // The pause spans the helper's `await`s, so genuinely concurrent test work
+  // (`Promise.all([helper(), ctx.fetch(…)])`) loses its events too. That is
+  // the same trade `email()` has always made, and sequential test code — all
+  // of it, in practice — is unaffected.
+  pauseRecording();
   let result: unknown;
   try {
     result = fn.apply(thisArg, args);
   } catch (err) {
+    resumeRecording();
     recordError(err);
     throw err;
   }
   if (result instanceof Promise) {
-    return result.then(recordResult, (err) => {
-      recordError(err);
-      throw err;
-    });
+    return result.then(
+      (value) => {
+        resumeRecording();
+        return recordResult(value);
+      },
+      (err) => {
+        resumeRecording();
+        recordError(err);
+        throw err;
+      },
+    );
   }
+  resumeRecording();
   return recordResult(result);
 }
 
+/** Record a fake-helper call's render annotation as a child of the call's
+ * own `fake` event — the same `parentSeq` grouping `ctx.poll` uses for the
+ * iteration it kept, so the annotated view folds into the fake step's
+ * detail panel instead of taking a timeline row of its own.
+ *
+ * The child is the event kind that already knows how to draw this: an
+ * `email` annotation records the very event the built-in `email()`
+ * component's mailbox helpers record, so it renders with no new code. It
+ * carries the fake's name and member as its service/op, and the parent's
+ * duration, since it describes that same call.
+ *
+ * Only the success path is annotated: a helper that threw returned no value
+ * to annotate, so it's a plain `fake` error event. */
+function recordAnnotationChild(
+  fakeName: string,
+  member: string,
+  annotation: RenderAnnotation,
+  durationMs: number,
+  parentSeq: number,
+): void {
+  switch (annotation.kind) {
+    case "email":
+      recordEmail({
+        parentSeq,
+        annotation: true,
+        service: fakeName,
+        op: member,
+        message: annotation.message,
+        messages: annotation.messages,
+        count: annotation.count,
+        durationMs,
+      });
+      break;
+    case "chat":
+      // A chat has no event kind of its own: it describes itself in
+      // presentation terms (title + blocks), which is the seam a new step
+      // type is supposed to use. `kind` stays an opaque grouping label.
+      recordStep({
+        kind: "chat",
+        parentSeq,
+        annotation: true,
+        title: annotation.title ?? `${fakeName}.${member}`,
+        blocks: annotation.blocks,
+        durationMs,
+      });
+      break;
+  }
+}
+
 function errMessage(err: unknown): string {
   return (err as Error)?.message ?? String(err);
 }

package/src/index.ts

@@ -34,6 +34,24 @@ import type { OpTag, Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
 // `unwrap(x)` free function. See the `.unwrap()` discipline section of `spectest docs`.
 export { field } from "./inspect.js";
 
+// Render annotations for fake helpers: a helper returns
+// `annotate(value, "email", { … })` or `annotate(value, "chat", { … })`
+// when its value is one of those, and the fake step it records gains a
+// nested event drawing it — an email mail-client style, a conversation as
+// bubbles — which the step's panel leads with, tabbing to the raw JSON
+// value. The kind picks the options' type, and the test still gets the raw
+// value, with the raw value's type — see `annotate.ts`.
+export { annotate } from "./annotate.js";
+export type {
+  Annotated,
+  AnnotationKind,
+  AnnotationOptions,
+  ChatAnnotation,
+  ChatMessageAnnotation,
+  EmailAnnotation,
+} from "./annotate.js";
+import type { Annotated } from "./annotate.js";
+
 // Instrumented client primitives — drop-in replacements for Bun's native
 // clients that record each operation on the test event log and return their
 // results inspect-wrapped, so `expect(...)` on a result links back to the op
@@ -1633,6 +1651,10 @@ export interface FakeDefinition<
    * Every call is tracked in the test timeline: it records a `fake` step
    * and the return value is tagged so a later `expect(...)` on it nests
    * under that step in the UI (same provenance as `fetch`/db results).
+   * The step renders the return value as JSON; wrap it in {@link annotate}
+   * to add a richer view (an email, today) that the step's panel leads with,
+   * the JSON one tab away — the test still receives the raw value, unchanged
+   * and unchanged in type.
    *
    * Receives the fake's `state` plus a {@link FakeContext} `ctx`, so a
    * helper can provision/teardown runtime services just like the handler.
@@ -1703,12 +1725,20 @@ export type FakesMap = Record<string, FakeDefinition<any, any>>;
  * `components/k3s.ts`, extended to cover synchronous returns. */
 type WrappedHelpers<H> = {
   [K in keyof H]: H[K] extends (...args: infer A) => Promise<infer R>
-    ? (...args: A) => Promise<Wrapped<R>>
+    ? (...args: A) => Promise<Wrapped<Unannotated<R>>>
     : H[K] extends (...args: infer A) => infer R
-      ? (...args: A) => [R] extends [void] ? void : Wrapped<R>
+      ? (...args: A) => [R] extends [void] ? void : Wrapped<Unannotated<R>>
       : H[K];
 };
 
+/** A helper's return type as the *test* sees it. {@link annotate} boxes the
+ * value in an {@link Annotated} to pick how the step renders; the daemon
+ * opens that box at the helper boundary, so the annotation never reaches
+ * the caller — in the types either. Distributes over a union, so a helper
+ * that annotates only when it has something (`return m && annotate(m, "email")`)
+ * still reads as `T | undefined`. */
+type Unannotated<R> = R extends Annotated<infer U> ? U : R;
+
 /** Awaited return type of a fake's `helpers` factory (with each result
  * inspect-wrapped, see {@link WrappedHelpers}), or `{ state: S }` (the
  * default) when the user didn't ship one. */

package/src/recorder.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  recordEmail,
+  recordFake,
+  recordWait,
+  recorderEventCount,
+  recorderMarkChildren,
+  reserveEvent,
+  startRecording,
+  stopRecording,
+} from "./recorder.js";
+
+describe("markChildren", () => {
+  test("groups a poll's kept iteration under the wait", () => {
+    startRecording();
+    const from = recorderEventCount();
+    recordFake({ fake: "resend", member: "lastEmailTo", args: [], durationMs: 1 });
+    const wait = recordWait({ description: "the mail arrives", attempts: 1, durationMs: 2, passed: true })!;
+    recorderMarkChildren(from, wait);
+    const events = stopRecording();
+
+    const fake = events.find((e) => e.kind === "fake")!;
+    expect(fake.parentSeq).toBe(wait);
+    // The wait never becomes its own child.
+    expect(events.find((e) => e.kind === "wait")!.parentSeq).toBeUndefined();
+  });
+
+  // A fake helper's `annotate(...)` child is that call's value, so it stays a
+  // child of the FAKE event even when the call happened inside a poll
+  // predicate. Overwriting it with the wait's seq made the wait itself render
+  // as the email, with the fake call showing raw JSON below it.
+  test("keeps an already-grouped event under its own parent", () => {
+    startRecording();
+    const from = recorderEventCount();
+    // The call's own slot is reserved first, exactly as invokeFakeHelper does.
+    const resv = reserveEvent();
+    const fakeSeq = recordFake(
+      { fake: "resend", member: "lastEmailTo", args: [], durationMs: 1 },
+      resv,
+    )!;
+    recordEmail({
+      parentSeq: fakeSeq,
+      annotation: true,
+      service: "resend",
+      op: "lastEmailTo",
+      message: { subject: "Ditt formulär" },
+      durationMs: 1,
+    });
+    const wait = recordWait({ description: "the mail arrives", attempts: 1, durationMs: 2, passed: true })!;
+    recorderMarkChildren(from, wait);
+    const events = stopRecording();
+
+    expect(events.find((e) => e.kind === "fake")!.parentSeq).toBe(wait);
+    expect(events.find((e) => e.kind === "email")!.parentSeq).toBe(fakeSeq);
+  });
+});

package/src/recorder.ts

@@ -26,7 +26,11 @@ export type TestEvent =
   | WaitEvent
   | FakeEvent
   | EnvEvent
-  | EmailEvent;
+  | EmailEvent
+  // Open `kind`, so it goes last: narrowing the union by a literal kind
+  // still reaches the specific member above, and this one carries anything
+  // a component describes in presentation terms.
+  | StepEvent;
 
 interface BaseEvent {
   /** Order of *start* within the test. Reserved when an op begins (see
@@ -47,6 +51,15 @@ interface BaseEvent {
    * timelines. The parent event is identified by its `seq`.
    */
   parentSeq?: number;
+  /**
+   * Set when this event is not an op of its own but *another view of its
+   * parent's value* — what a fake helper's `annotate(...)` records
+   * (`annotate.ts`). The two kinds of `parentSeq` child read differently
+   * and render differently: a `ctx.poll` iteration is work the step did,
+   * and belongs below it; an annotation is the same value drawn better,
+   * and belongs in place of it (the dashboard tabs between the two).
+   */
+  annotation?: boolean;
 }
 
 export interface ExecEvent extends BaseEvent {
@@ -348,14 +361,17 @@ export interface EmailEventMessage {
   attachments?: { filename: string; contentType: string; size: number }[];
 }
 
-/** One row of a mailbox listing embedded on an {@link EmailEvent}. */
-export interface EmailEventSummary {
-  from?: string;
-  to?: string[];
-  subject?: string;
-  /** Plain-text preview of the body. */
+/**
+ * One row of a mailbox listing embedded on an {@link EmailEvent}. A row is a
+ * message: the dashboard lists rows as `to` + subject and expands the one you
+ * click into the same view a single-message op renders, so whatever body the
+ * producer has belongs here. Mailpit's list API returns no bodies, so
+ * `email()`'s own listings fill only the header fields plus `snippet` — a row
+ * with no body expands to its preview instead.
+ */
+export interface EmailEventSummary extends EmailEventMessage {
+  /** Plain-text preview of the body, shown when the row carries no body. */
   snippet?: string;
-  date?: string;
 }
 
 /**
@@ -370,9 +386,13 @@ export interface EmailEventSummary {
  */
 export interface EmailEvent extends BaseEvent {
   kind: "email";
-  /** Service key of the mail server (`ctx.svc.<service>`). */
+  /** Service key of the mail server (`ctx.svc.<service>`) — or the fake's
+   *  name, when a fake helper annotated its return with `annotate(v, "email")`
+   *  (`annotate.ts`) and this event hangs off that call's `fake` one as a
+   *  `parentSeq` child. */
   service: string;
-  /** Helper called, e.g. `"lastEmail"`. */
+  /** Helper called, e.g. `"lastEmail"` — the fake's member name for an
+   *  annotated fake-helper call. */
   op: string;
   /** Human-readable match criteria, e.g. `to alice@example.com`. */
   query?: string;
@@ -621,13 +641,22 @@ class Recorder {
     }
   }
 
-  /** Stamp `parentSeq` onto every event at index >= `startIdx`. Used
-   *  by `ctx.poll` to group the kept iteration's events under the
-   *  resulting wait event. */
+  /** Stamp `parentSeq` onto every event at index >= `startIdx` that isn't
+   *  already grouped under something else. Used by `ctx.poll` to group the
+   *  kept iteration's events under the resulting wait event.
+   *
+   *  An event that already carries a `parentSeq` keeps it: it belongs to a
+   *  step *inside* this one, and re-parenting it here would flatten the
+   *  nesting the UI renders from. The case that made this matter is a fake
+   *  helper called in a poll predicate — its `annotate(...)` child is the
+   *  fake call's value, and stamping the wait's seq over it made the WAIT
+   *  render as an email/chat while the fake call showed raw JSON. Its
+   *  ancestor is still the wait, one level up through the fake event. */
   markChildren(startIdx: number, parentSeq: number): void {
     for (let i = startIdx; i < this.events.length; i++) {
       const ev = this.events[i]!;
       if (ev.seq === parentSeq) continue;
+      if (ev.parentSeq !== undefined) continue;
       ev.parentSeq = parentSeq;
     }
   }
@@ -803,6 +832,59 @@ export function recordEnv(
   return active() ? current!.push({ kind: "env", ...ev }, reservation) : undefined;
 }
 
+/**
+ * One block of step detail, in the dashboard's presentation vocabulary
+ * (`crates/control-plane/src/web/blocks.rs`, which owns the closed set).
+ * A server that predates a block type skips it rather than failing, so a
+ * newer SDK's step degrades to the blocks the server knows.
+ */
+export type StepBlock =
+  | { type: "text"; text: string }
+  | { type: "code"; code: string; lang?: string; label?: string }
+  | { type: "json"; value: unknown; label?: string }
+  | { type: "kv"; rows: { label: string; value?: string; error?: boolean }[] }
+  | { type: "table"; columns: string[]; rows: unknown[][] }
+  | { type: "htmlSandbox"; html: string; label?: string }
+  | { type: "chat"; messages: ChatBlockMessage[]; label?: string };
+
+/** One message of a `chat` block. */
+export interface ChatBlockMessage {
+  /** Who sent it. The transcript is drawn as the end user would see it, so
+   *  `self` (the end user's own messages) sits on the right and `other` on
+   *  the left. */
+  side?: "self" | "other";
+  text?: string;
+  /** Arrived in *this* step: drawn with an entrance animation. Only the
+   *  producer knows this, so only the producer sets it. */
+  new?: boolean;
+}
+
+/**
+ * A step that describes itself in presentation terms — a title plus an
+ * ordered list of blocks — instead of as one of the recorder's hard-coded
+ * kinds. This is the seam that lets a component ship a new kind of step
+ * with no server change: `kind` stays an opaque grouping/diff-alignment
+ * label and never decides how the step draws.
+ */
+export interface StepEvent extends BaseEvent {
+  /** Opaque. Groups the step and aligns it across runs; never matched on
+   *  to pick a renderer. */
+  kind: string;
+  /** The step's one-line summary in the timeline. */
+  title: string;
+  blocks?: StepBlock[];
+  status?: "passed" | "failed" | "error";
+  durationMs?: number;
+  error?: string;
+}
+
+export function recordStep(
+  ev: Omit<StepEvent, "seq" | "tOffsetMs">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push(ev, reservation) : undefined;
+}
+
 export function recordEmail(
   ev: Omit<EmailEvent, "seq" | "tOffsetMs" | "kind">,
   reservation?: EventReservation,