@echovisionlab/geul-common 0.5.0 → 0.6.1

package/package.json

@@ -2,7 +2,7 @@
   "name": "@echovisionlab/geul-common",
   "description": "Shared TypeScript contracts and helpers for Geul editors, collaboration, localized content, media blocks, pages, posts, and runtime events.",
   "author": "state303 <state303@dsub.io>",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "private": false,
   "type": "module",
   "repository": {
@@ -49,6 +49,7 @@
     "./collaboration/page": "./src/collaboration/page.ts",
     "./collaboration/post": "./src/collaboration/post.ts",
     "./collaboration/post-series": "./src/collaboration/post-series.ts",
+    "./collaboration/protocol": "./src/collaboration/protocol.ts",
     "./collaboration/release": "./src/collaboration/release.ts",
     "./collaboration/runtime-events": "./src/collaboration/runtime-events.ts",
     "./collaboration/work": "./src/collaboration/work.ts",
@@ -64,7 +65,7 @@
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.16.0",
-    "@echovisionlab/geul-proto": "^0.5.0",
+    "@echovisionlab/geul-proto": "^0.6.0",
     "diff": "9.0.0",
     "zod": "^4.6.5"
   },

package/src/collaboration/protocol.ts

@@ -0,0 +1,609 @@
+/**
+ * Collaboration control-plane protocol v3: the single definition of every Hocuspocus stateless
+ * message exchanged by the editor (geul-web) and the collaboration server (geul-editor-collab).
+ * Specification: docs/collaboration-protocol.md. Both sides parse with these schemas; neither
+ * defines its own message shapes.
+ *
+ * Typed bodies (`document`, `presentLocaleValues`, metadata payload values, form schemas) are
+ * protobuf or domain JSON validated by their owning modules after the envelope is accepted.
+ */
+import * as z from "zod/mini";
+import { editorRuntimeEventSchema } from "./runtime-events.ts";
+
+export const COLLABORATION_PROTOCOL_VERSION = 3 as const;
+/** Upper bound for a client control frame; bootstrap is the only large message and is server-sent. */
+export const MAX_CLIENT_CONTROL_MESSAGE_BYTES = 16 * 1024;
+/** `form.schema.patch` carries the previous and next full schemas, so it gets its own bound. */
+export const MAX_FORM_SCHEMA_PATCH_MESSAGE_BYTES = 1024 * 1024;
+
+/**
+ * Connection parameters naming the typed body a client already holds (the SSR read). Collab omits
+ * `room.bootstrap.document` only when both the revision and the body digest match its own body.
+ */
+export const KNOWN_DOCUMENT_REVISION_PARAM = "knownDocumentRevision";
+export const KNOWN_DOCUMENT_DIGEST_PARAM = "knownDocumentDigest";
+
+/**
+ * 64-bit non-cryptographic digest (cyrb64) of a typed body's protobuf binary. It only decides
+ * whether a body may be omitted; the client still verifies the Yjs update against the body it
+ * holds, so a collision costs a reconnect, never correctness.
+ */
+export function documentBodyDigest(bytes: Uint8Array): string {
+  let h1 = 0xdeadbeef ^ bytes.length;
+  let h2 = 0x41c6ce57 ^ bytes.length;
+  for (const byte of bytes) {
+    h1 = Math.imul(h1 ^ byte, 2654435761);
+    h2 = Math.imul(h2 ^ byte, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+  h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+  h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+  return (
+    (h2 >>> 0).toString(16).padStart(8, "0") +
+    (h1 >>> 0).toString(16).padStart(8, "0")
+  );
+}
+
+const v = z.literal(COLLABORATION_PROTOCOL_VERSION);
+const nonEmpty = z.string().check(z.trim(), z.minLength(1));
+const uuid = z.string().check(z.uuid());
+const base64 = z
+  .string()
+  .check(
+    z.regex(
+      /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u,
+    ),
+  );
+/** Opaque target-locale revision token issued by the API. */
+export const targetRevisionSchema = z
+  .string()
+  .check(
+    z.refine(
+      (value) => value.trim().length > 0,
+      "Target revision must be a nonblank opaque token.",
+    ),
+  );
+const json = z.unknown();
+
+export const blockRoomDocumentTypeSchema = z.enum([
+  "post",
+  "page",
+  "work",
+  "program-event",
+  "artist",
+  "label",
+  "release",
+  "campaign",
+  "email-template",
+  "terms-history",
+  "privacy-history",
+]);
+
+export const reloadReasonSchema = z.enum([
+  "deploy_or_restart",
+  "epoch_mismatch",
+  "external_update",
+  "conflict",
+  "permission",
+  "state_mismatch",
+]);
+export type ReloadReason = z.infer<typeof reloadReasonSchema>;
+
+export const accessEndedReasonSchema = z.enum([
+  "permission_revoked",
+  "session_expired",
+]);
+export type AccessEndedReason = z.infer<typeof accessEndedReasonSchema>;
+
+/**
+ * Reasons a refused admission is temporary (the Hocuspocus permission-denied frame carries the
+ * reason): the collab host is stopping or could not reach authorization. The client keeps its
+ * state and retries with backoff; any other unknown reason is not retried.
+ */
+export const admissionRetryReasonSchema = z.enum([
+  "service_stopping",
+  "authorization_unavailable",
+]);
+export type AdmissionRetryReason = z.infer<typeof admissionRetryReasonSchema>;
+
+export function isAdmissionRetryReason(
+  reason: string,
+): reason is AdmissionRetryReason {
+  return admissionRetryReasonSchema.safeParse(reason).success;
+}
+
+export const localeMetadataSchema = z.strictObject({
+  locale: nonEmpty,
+  title: z.optional(z.string()),
+  summary: z.optional(z.string()),
+  subject: z.optional(z.string()),
+  creditNotes: z.optional(
+    z.array(z.strictObject({ creditId: nonEmpty, note: z.string() })),
+  ),
+});
+export type LocaleMetadata = z.infer<typeof localeMetadataSchema>;
+
+export const metadataOperationSchema = z.enum([
+  "locale",
+  "document",
+  "page_layout",
+]);
+export type MetadataOperation = z.infer<typeof metadataOperationSchema>;
+
+export const metadataUpdateSchema = z.strictObject({
+  operation: metadataOperationSchema,
+  values: z.record(z.string(), json),
+  sequence: z.number().check(z.int(), z.positive()),
+});
+export type MetadataUpdate = z.infer<typeof metadataUpdateSchema>;
+
+export const metadataAckSchema = z.strictObject({
+  documentRevision: uuid,
+  targetRevision: z.optional(targetRevisionSchema),
+  changed: z.boolean(),
+  sourceChanged: z.boolean(),
+  changedLocales: z.array(z.string()),
+  locale: nonEmpty,
+  metadataUpdate: metadataUpdateSchema,
+});
+export type MetadataAck = z.infer<typeof metadataAckSchema>;
+
+/** Yjs coverage a durable save acknowledges: client clocks plus deleted ranges. */
+export const durabilityCoverageSchema = z.strictObject({
+  stateVector: base64,
+  deleted: z.record(
+    z.string().check(z.regex(/^\d+$/u)),
+    z.array(
+      z.strictObject({
+        clock: z.number().check(z.int(), z.nonnegative()),
+        len: z.number().check(z.int(), z.positive()),
+      }),
+    ),
+  ),
+});
+export type DurabilityCoverage = z.infer<typeof durabilityCoverageSchema>;
+
+export const roomRevisionSchema = z.strictObject({
+  documentRevision: uuid,
+  targetRevision: z.optional(targetRevisionSchema),
+  sourceLocale: nonEmpty,
+  locale: nonEmpty,
+  localeExists: z.boolean(),
+});
+export type RoomRevision = z.infer<typeof roomRevisionSchema>;
+
+export const protocolErrorSchema = z.strictObject({
+  code: nonEmpty,
+  message: z.optional(z.string()),
+  reloadReason: z.optional(reloadReasonSchema),
+  /**
+   * false: repeating the same request cannot succeed (permission, validation, missing entity), so
+   * the client stops retrying and keeps the intent as a recoverable backup. Absent means retryable.
+   */
+  retryable: z.optional(z.boolean()),
+});
+export type ProtocolError = z.infer<typeof protocolErrorSchema>;
+
+function result<
+  Kind extends string,
+  Value extends Record<string, z.core.$ZodType>,
+>(kind: Kind, value: Value) {
+  return z.discriminatedUnion("ok", [
+    z.strictObject({
+      v,
+      kind: z.literal(kind),
+      requestId: uuid,
+      ok: z.literal(true),
+      ...value,
+    }),
+    z.strictObject({
+      v,
+      kind: z.literal(kind),
+      requestId: uuid,
+      ok: z.literal(false),
+      error: protocolErrorSchema,
+    }),
+  ]);
+}
+
+// ---- Client → server -------------------------------------------------------------------------
+
+export const bootstrapAckSchema = z.strictObject({
+  v,
+  kind: z.literal("room.bootstrap_ack"),
+  challenge: nonEmpty,
+  stateVector: base64,
+});
+export const metadataRequestSchema = z.strictObject({
+  v,
+  kind: z.literal("room.metadata"),
+  requestId: uuid,
+  operation: metadataOperationSchema,
+  payload: json,
+});
+export const revisionRequestSchema = z.strictObject({
+  v,
+  kind: z.literal("room.revision"),
+  requestId: uuid,
+});
+export const flushRequestSchema = z.strictObject({
+  v,
+  kind: z.literal("room.flush"),
+  requestId: uuid,
+});
+export const formSchemaPatchRequestSchema = z.strictObject({
+  v,
+  kind: z.literal("form.schema.patch"),
+  requestId: uuid,
+  previousSchema: json,
+  nextSchema: json,
+});
+
+export const clientMessageSchema = z.discriminatedUnion("kind", [
+  bootstrapAckSchema,
+  metadataRequestSchema,
+  revisionRequestSchema,
+  flushRequestSchema,
+  formSchemaPatchRequestSchema,
+]);
+export type ClientMessage = z.infer<typeof clientMessageSchema>;
+
+// ---- Server → client -------------------------------------------------------------------------
+
+export const bootstrapSchema = z.strictObject({
+  v,
+  kind: z.literal("room.bootstrap"),
+  bootstrapChallenge: nonEmpty,
+  documentName: nonEmpty,
+  documentType: blockRoomDocumentTypeSchema,
+  /** Omitted when the connection's known revision and body digest match this body. */
+  document: z.optional(json),
+  documentRevision: uuid,
+  sourceLocale: nonEmpty,
+  locale: nonEmpty,
+  localeExists: z.boolean(),
+  targetRevision: z.optional(targetRevisionSchema),
+  presentLocaleValues: z.array(json),
+  sourceMetadata: localeMetadataSchema,
+  localeMetadata: z.optional(localeMetadataSchema),
+  documentMetadata: z.record(z.string(), json),
+  metadataSequence: z.number().check(z.int(), z.nonnegative()),
+  blockCatalogFingerprint: nonEmpty,
+  serverInstanceId: nonEmpty,
+  roomEpoch: uuid,
+  yjsBootstrapUpdate: base64,
+});
+export type BootstrapMessage = z.infer<typeof bootstrapSchema>;
+
+export const readySchema = z.strictObject({
+  v,
+  kind: z.literal("room.ready"),
+  bootstrapChallenge: nonEmpty,
+});
+export const metadataResultSchema = result("room.metadata_result", {
+  ack: metadataAckSchema,
+});
+export const revisionResultSchema = result("room.revision_result", {
+  revision: roomRevisionSchema,
+});
+export const flushResultSchema = result("room.flush_result", {
+  persisted: durabilityCoverageSchema,
+});
+export const formSchemaPatchResultSchema = result("form.schema.patch_result", {
+  canonicalSchema: json,
+});
+export const persistedSchema = z.strictObject({
+  v,
+  kind: z.literal("room.persisted"),
+  documentName: nonEmpty,
+  ...durabilityCoverageSchema.shape,
+});
+export const metadataChangedSchema = z.strictObject({
+  v,
+  kind: z.literal("room.metadata_changed"),
+  documentName: nonEmpty,
+  ack: metadataAckSchema,
+});
+export const formSchemaChangedSchema = z.strictObject({
+  v,
+  kind: z.literal("form.schema.changed"),
+  documentName: nonEmpty,
+  canonicalSchema: json,
+});
+export const reloadSchema = z.strictObject({
+  v,
+  kind: z.literal("room.reload"),
+  reloadReason: reloadReasonSchema,
+});
+/**
+ * The connection's access level changed while it stays open: `view` makes it read-only (edits are
+ * no longer accepted), `edit` restores editing. Access that ends entirely is `room.access_ended`.
+ */
+export const accessLevelSchema = z.enum(["view", "edit"]);
+export type AccessLevel = z.infer<typeof accessLevelSchema>;
+export const accessChangedSchema = z.strictObject({
+  v,
+  kind: z.literal("room.access_changed"),
+  access: accessLevelSchema,
+});
+export const accessEndedSchema = z.strictObject({
+  v,
+  kind: z.literal("room.access_ended"),
+  reason: accessEndedReasonSchema,
+});
+export const entityChangedSchema = z.strictObject({
+  v,
+  kind: z.literal("entity.changed"),
+  /** `{type}:{entityUUID}` of the resource. */
+  entity: nonEmpty,
+  scope: z.enum(["metadata", "document", "locale"]),
+  /** The authoritative document revision after the change. */
+  revision: z.optional(uuid),
+  locale: z.optional(nonEmpty),
+  /** Opaque per-tab write origin; never an authentication identity. */
+  origin: z.optional(nonEmpty),
+});
+export type EntityChangedMessage = z.infer<typeof entityChangedSchema>;
+export const interactiveMutationBeginSchema = z.strictObject({
+  v,
+  kind: z.literal("interactive_mutation.begin"),
+  mutationId: uuid,
+});
+export const interactiveMutationEndSchema = z.strictObject({
+  v,
+  kind: z.literal("interactive_mutation.end"),
+  mutationId: uuid,
+  outcome: z.enum(["accepted", "aborted"]),
+});
+
+/** Translation, OG, media and ingest status, carried unchanged inside the v3 envelope. */
+export const runtimeEventMessageSchema = z.strictObject({
+  v,
+  kind: z.literal("runtime.event"),
+  event: editorRuntimeEventSchema,
+});
+
+// The two-branch result unions are matched by kind before their `ok` discriminator.
+const serverSingleSchemas = [
+  bootstrapSchema,
+  readySchema,
+  persistedSchema,
+  metadataChangedSchema,
+  formSchemaChangedSchema,
+  reloadSchema,
+  accessChangedSchema,
+  accessEndedSchema,
+  entityChangedSchema,
+  interactiveMutationBeginSchema,
+  interactiveMutationEndSchema,
+  runtimeEventMessageSchema,
+] as const;
+const serverResultSchemas = {
+  "room.metadata_result": metadataResultSchema,
+  "room.revision_result": revisionResultSchema,
+  "room.flush_result": flushResultSchema,
+  "form.schema.patch_result": formSchemaPatchResultSchema,
+} as const;
+
+/** The result kind answering each client request kind. */
+const resultKindByRequestKind = new Map<
+  string,
+  keyof typeof serverResultSchemas
+>([
+  ["room.metadata", "room.metadata_result"],
+  ["room.revision", "room.revision_result"],
+  ["room.flush", "room.flush_result"],
+  ["form.schema.patch", "form.schema.patch_result"],
+]);
+
+export type ServerMessage =
+  | z.infer<(typeof serverSingleSchemas)[number]>
+  | z.infer<(typeof serverResultSchemas)[keyof typeof serverResultSchemas]>;
+export type ServerMessageKind = ServerMessage["kind"];
+export type ServerMessageOf<Kind extends ServerMessageKind> = Extract<
+  ServerMessage,
+  { kind: Kind }
+>;
+export type ClientMessageOf<Kind extends ClientMessage["kind"]> = Extract<
+  ClientMessage,
+  { kind: Kind }
+>;
+
+function kindOf(schema: { shape: { kind: z.ZodMiniLiteral<string> } }): string {
+  return schema.shape.kind.def.values[0] as string;
+}
+// Maps, not object literals: an inherited key such as "constructor" must not resolve to a schema.
+const serverSchemaByKind = new Map<string, z.ZodMiniType>([
+  ...serverSingleSchemas.map(
+    (schema) => [kindOf(schema), schema] as [string, z.ZodMiniType],
+  ),
+  ...Object.entries(serverResultSchemas),
+]);
+const clientMaxBytesByKind = new Map<string, number>([
+  [kindOf(bootstrapAckSchema), MAX_CLIENT_CONTROL_MESSAGE_BYTES],
+  [kindOf(metadataRequestSchema), MAX_CLIENT_CONTROL_MESSAGE_BYTES],
+  [kindOf(revisionRequestSchema), MAX_CLIENT_CONTROL_MESSAGE_BYTES],
+  [kindOf(flushRequestSchema), MAX_CLIENT_CONTROL_MESSAGE_BYTES],
+  [kindOf(formSchemaPatchRequestSchema), MAX_FORM_SCHEMA_PATCH_MESSAGE_BYTES],
+]);
+const MAX_ANY_CLIENT_CONTROL_MESSAGE_BYTES = Math.max(
+  ...clientMaxBytesByKind.values(),
+);
+
+/**
+ * `requestId` is present when a recognized request was rejected, so the receiver can answer it
+ * with a failed result (see `encodeRequestRejection`) instead of leaving the sender waiting.
+ */
+export type ParseFailure =
+  | { ok: false; reason: "invalid_json" | "not_an_object" }
+  | { ok: false; reason: "too_large"; kind?: string; requestId?: string }
+  | { ok: false; reason: "unsupported_version"; version: unknown }
+  | { ok: false; reason: "unknown_kind"; kind: unknown }
+  | {
+      ok: false;
+      reason: "invalid_shape";
+      kind: string;
+      issues: string;
+      requestId?: string;
+    };
+
+/** UTF-8 byte length, computed only when the UTF-16 length cannot already decide the bound. */
+function exceedsBytes(payload: string, maxBytes: number): boolean {
+  if (payload.length * 3 <= maxBytes) return false;
+  if (payload.length > maxBytes) return true;
+  return new TextEncoder().encode(payload).byteLength > maxBytes;
+}
+
+function requestIdOf(record: Record<string, unknown>): string | undefined {
+  return typeof record.requestId === "string" ? record.requestId : undefined;
+}
+
+function readEnvelope(
+  payload: string,
+  maxBytes?: number,
+): { ok: true; record: Record<string, unknown>; kind: unknown } | ParseFailure {
+  if (maxBytes !== undefined && exceedsBytes(payload, maxBytes)) {
+    return { ok: false, reason: "too_large" };
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(payload);
+  } catch {
+    return { ok: false, reason: "invalid_json" };
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, reason: "not_an_object" };
+  }
+  const record = value as Record<string, unknown>;
+  if (record.v !== COLLABORATION_PROTOCOL_VERSION) {
+    return { ok: false, reason: "unsupported_version", version: record.v };
+  }
+  return { ok: true, record, kind: record.kind };
+}
+
+function issues(error: z.core.$ZodError): string {
+  return error.issues
+    .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+    .join("; ");
+}
+
+type ParseResult<Message> = { ok: true; message: Message } | ParseFailure;
+
+/**
+ * Several independent listeners receive every stateless frame (save tracking, runtime events,
+ * entity changes, ...). Remembering the last frame lets them share one parse of the same payload.
+ * Parsed messages are shared between listeners and must be treated as read-only.
+ */
+function lastPayloadMemo<Message>(
+  parse: (payload: string) => ParseResult<Message>,
+): (payload: string) => ParseResult<Message> {
+  let lastPayload: string | undefined;
+  let lastResult: ParseResult<Message> | undefined;
+  return (payload) => {
+    if (payload !== lastPayload || !lastResult) {
+      lastResult = parse(payload);
+      lastPayload = payload;
+    }
+    return lastResult;
+  };
+}
+
+/** Parse a client→server control frame. Never throws. */
+export const parseClientMessage = lastPayloadMemo(
+  (payload): ParseResult<ClientMessage> => {
+    const envelope = readEnvelope(
+      payload,
+      MAX_ANY_CLIENT_CONTROL_MESSAGE_BYTES,
+    );
+    if (!envelope.ok) return envelope;
+    const kind = envelope.kind;
+    const maxBytes =
+      typeof kind === "string" ? clientMaxBytesByKind.get(kind) : undefined;
+    if (maxBytes === undefined)
+      return { ok: false, reason: "unknown_kind", kind };
+    const requestId = requestIdOf(envelope.record);
+    if (exceedsBytes(payload, maxBytes)) {
+      return {
+        ok: false,
+        reason: "too_large",
+        kind: kind as string,
+        requestId,
+      };
+    }
+    const parsed = clientMessageSchema.safeParse(envelope.record);
+    if (parsed.success) return { ok: true, message: parsed.data };
+    return {
+      ok: false,
+      reason: "invalid_shape",
+      kind: kind as string,
+      issues: issues(parsed.error),
+      requestId,
+    };
+  },
+);
+
+/** Parse a server→client control frame. Never throws. */
+export const parseServerMessage = lastPayloadMemo(
+  (payload): ParseResult<ServerMessage> => {
+    const envelope = readEnvelope(payload);
+    if (!envelope.ok) return envelope;
+    const kind = envelope.kind;
+    const schema =
+      typeof kind === "string" ? serverSchemaByKind.get(kind) : undefined;
+    if (!schema) return { ok: false, reason: "unknown_kind", kind };
+    const parsed = schema.safeParse(envelope.record);
+    return parsed.success
+      ? { ok: true, message: parsed.data as ServerMessage }
+      : {
+          ok: false,
+          reason: "invalid_shape",
+          kind: kind as string,
+          issues: issues(parsed.error),
+        };
+  },
+);
+
+type Unversioned<Message> = Message extends unknown
+  ? Omit<Message, "v">
+  : never;
+
+/** Serialize a control frame, stamping the protocol version. */
+export function encodeMessage(
+  message: Unversioned<ClientMessage> | Unversioned<ServerMessage>,
+): string {
+  return JSON.stringify({ v: COLLABORATION_PROTOCOL_VERSION, ...message });
+}
+
+/**
+ * The failed result answering a rejected request, or undefined when the frame was not a
+ * recognizable request. The error code is the parse failure reason.
+ */
+export function encodeRequestRejection(
+  failure: ParseFailure,
+): string | undefined {
+  if (failure.reason !== "too_large" && failure.reason !== "invalid_shape")
+    return undefined;
+  const resultKind =
+    failure.kind === undefined
+      ? undefined
+      : resultKindByRequestKind.get(failure.kind);
+  const requestId = failure.requestId;
+  if (!resultKind || !requestId || !uuid.safeParse(requestId).success)
+    return undefined;
+  return encodeMessage({
+    kind: resultKind,
+    requestId,
+    ok: false,
+    error: { code: failure.reason, retryable: false },
+  });
+}
+
+/** Whether a client frame fits the bound the receiver enforces for its kind. */
+export function fitsClientMessageBound(
+  kind: ClientMessage["kind"],
+  payload: string,
+): boolean {
+  const maxBytes = clientMaxBytesByKind.get(kind);
+  return maxBytes !== undefined && !exceedsBytes(payload, maxBytes);
+}

package/src/collaboration/runtime-events.ts

@@ -1,192 +1,5 @@
 import * as z from "zod/mini";
 
-export type RuntimeEntityType =
-  | "post"
-  | "page"
-  | "work"
-  | "artist"
-  | "label"
-  | "release"
-  | "series"
-  | "form"
-  | "program_event"
-  | "menu"
-  | "site"
-  | "site_setting"
-  | "email_template"
-  | "email_layout"
-  | "campaign"
-  | "privacy"
-  | "terms";
-
-export type TranslationLifecycleRuntimeStatus = "failed";
-
-export type MediaProcessingRuntimeStatus = "processing" | "ready" | "failed";
-
-export type OgGenerationRuntimeEntityType =
-  | "post"
-  | "page"
-  | "work"
-  | "artist"
-  | "label"
-  | "release"
-  | "series"
-  | "form"
-  | "site"
-  | "privacy"
-  | "terms";
-
-export type OgGenerationRuntimeStatus =
-  "queued" | "processing" | "ready" | "failed" | "superseded" | "cancelled";
-
-export function isOgGenerationRuntimeTerminal(
-  status: OgGenerationRuntimeStatus,
-): boolean {
-  return (
-    status === "ready" ||
-    status === "failed" ||
-    status === "superseded" ||
-    status === "cancelled"
-  );
-}
-
-export type FileIngestRuntimeSource = "upload" | "embed";
-
-export type FileIngestRuntimeStage =
-  | "uploading"
-  | "downloading"
-  | "finalized"
-  | "attached"
-  | "completed"
-  | "expired"
-  | "failed"
-  | "unknown";
-
-export interface RuntimeEventEnvelope<K extends string, P> {
-  version: 1;
-  kind: K;
-  entityType: RuntimeEntityType;
-  entityId: string;
-  locale?: string;
-  correlationId?: string;
-  sequence?: number;
-  timestampMs: number;
-  payload: P;
-}
-
-export interface OgGenerationLifecycleRuntimePayload {
-  generationId: string;
-  runId: string;
-  status: OgGenerationRuntimeStatus;
-  assetId?: string;
-  assetUrl?: string;
-  errorCode?: string;
-  error?: string;
-  replacementGenerationId?: string;
-}
-
-export interface RenderCompleteRuntimePayload {
-  contentHash: string;
-  success: boolean;
-  error?: string;
-}
-
-export interface MediaProcessingRuntimeOutputs {
-  spectrogramAssetId?: string;
-  thumbnailAssetId?: string;
-  hlsGenerationId?: string;
-  durationSeconds?: number;
-  waveformAssetId?: string;
-}
-
-export interface MediaProcessingLifecycleRuntimePayload {
-  fileId: string;
-  slotId?: string;
-  attemptId?: string;
-  status: MediaProcessingRuntimeStatus;
-  percentage?: number;
-  outputs?: MediaProcessingRuntimeOutputs;
-  error?: string;
-  trackId?: string;
-  releaseId?: string;
-}
-
-export function isMediaProcessingRuntimeReady(payload: {
-  status?: MediaProcessingRuntimeStatus | null;
-}): boolean {
-  return payload.status === "ready";
-}
-
-export interface FileIngestLifecycleRuntimePayload {
-  fileId: string;
-  uploadId?: string;
-  mediaKind?: string;
-  slotId?: string;
-  attemptId?: string;
-  source: FileIngestRuntimeSource;
-  stage: FileIngestRuntimeStage;
-  progress: number;
-  bytesCompleted?: number;
-  bytesTotal?: number;
-  fileName?: string;
-  mimeType?: string;
-  fileSize?: number;
-  error?: string;
-  trackId?: string;
-  releaseId?: string;
-}
-
-export interface TranslationLifecycleRuntimePayload {
-  jobId: string;
-  targetLocale: string;
-  status: TranslationLifecycleRuntimeStatus;
-  error?: string;
-}
-
-export interface RuntimeErrorPayload {
-  code: string;
-  message: string;
-  retryable?: boolean;
-  source?: "backend" | "collab" | "worker";
-  details?: Record<string, string | number | boolean | null>;
-}
-
-export interface OgGenerationLifecycleRuntimeEvent extends RuntimeEventEnvelope<
-  "og.lifecycle",
-  OgGenerationLifecycleRuntimePayload
-> {
-  entityType: OgGenerationRuntimeEntityType;
-  correlationId: string;
-}
-export type RenderCompleteRuntimeEvent = RuntimeEventEnvelope<
-  "render.complete",
-  RenderCompleteRuntimePayload
->;
-export type MediaProcessingLifecycleRuntimeEvent = RuntimeEventEnvelope<
-  "media.processing.lifecycle",
-  MediaProcessingLifecycleRuntimePayload
->;
-export type FileIngestLifecycleRuntimeEvent = RuntimeEventEnvelope<
-  "file.ingest.lifecycle",
-  FileIngestLifecycleRuntimePayload
->;
-export type TranslationLifecycleRuntimeEvent = RuntimeEventEnvelope<
-  "translation.lifecycle",
-  TranslationLifecycleRuntimePayload
->;
-export type RuntimeErrorEvent = RuntimeEventEnvelope<
-  "runtime.error",
-  RuntimeErrorPayload
->;
-
-export type EditorRuntimeEvent =
-  | OgGenerationLifecycleRuntimeEvent
-  | RenderCompleteRuntimeEvent
-  | MediaProcessingLifecycleRuntimeEvent
-  | FileIngestLifecycleRuntimeEvent
-  | TranslationLifecycleRuntimeEvent
-  | RuntimeErrorEvent;
-
 export const runtimeEntityTypeSchema = z.enum([
   "post",
   "page",
@@ -365,23 +178,26 @@ export const mediaProcessingLifecycleRuntimePayloadSchema = z
     }),
   );
 
+export const fileIngestRuntimeSourceSchema = z.enum(["upload", "embed"]);
+export const fileIngestRuntimeStageSchema = z.enum([
+  "uploading",
+  "downloading",
+  "finalized",
+  "attached",
+  "completed",
+  "expired",
+  "failed",
+  "unknown",
+]);
+
 export const fileIngestLifecycleRuntimePayloadSchema = z.strictObject({
   fileId: z.string().check(z.minLength(1)),
   uploadId: z.optional(z.string()),
   mediaKind: z.optional(z.string()),
   slotId: z.optional(z.string()),
   attemptId: z.optional(z.string()),
-  source: z.enum(["upload", "embed"]),
-  stage: z.enum([
-    "uploading",
-    "downloading",
-    "finalized",
-    "attached",
-    "completed",
-    "expired",
-    "failed",
-    "unknown",
-  ]),
+  source: fileIngestRuntimeSourceSchema,
+  stage: fileIngestRuntimeStageSchema,
   progress: z.int().check(z.minimum(0), z.maximum(100)),
   bytesCompleted: z.optional(z.int().check(z.nonnegative())),
   bytesTotal: z.optional(z.int().check(z.nonnegative())),
@@ -393,15 +209,11 @@ export const fileIngestLifecycleRuntimePayloadSchema = z.strictObject({
   releaseId: z.optional(z.string()),
 });
 
-const localeScopedOgEntityTypes = new Set<OgGenerationRuntimeEntityType>([
-  "post",
-  "page",
-  "form",
-  "privacy",
-  "terms",
-]);
+const localeScopedOgEntityTypes = new Set<
+  z.infer<typeof ogGenerationRuntimeEntityTypeSchema>
+>(["post", "page", "form", "privacy", "terms"]);
 
-const ogGenerationLifecycleRuntimeEventSchema = z
+export const ogGenerationLifecycleRuntimeEventSchema = z
   .strictObject({
     version: z.literal(1),
     kind: z.literal("og.lifecycle"),
@@ -440,30 +252,17 @@ const ogGenerationLifecycleRuntimeEventSchema = z
     }),
   );
 
+export const translationLifecycleRuntimeStatusSchema = z.literal("failed");
+
 export const translationLifecycleRuntimePayloadSchema = z.strictObject({
   jobId: z.string().check(z.minLength(1)),
   targetLocale: z.string().check(z.minLength(1)),
-  status: z.literal("failed"),
+  status: translationLifecycleRuntimeStatusSchema,
   error: z.optional(z.string()),
 });
 
 export const editorRuntimeEventSchema = z.discriminatedUnion("kind", [
   ogGenerationLifecycleRuntimeEventSchema,
-  z.strictObject({
-    version: z.literal(1),
-    kind: z.literal("render.complete"),
-    entityType: runtimeEntityTypeSchema,
-    entityId: z.string().check(z.minLength(1)),
-    locale: z.optional(z.string()),
-    correlationId: z.optional(z.string()),
-    sequence: z.optional(z.int()),
-    timestampMs: z.int(),
-    payload: z.strictObject({
-      contentHash: z.string(),
-      success: z.boolean(),
-      error: z.optional(z.string()),
-    }),
-  }),
   z.strictObject({
     version: z.literal(1),
     kind: z.literal("media.processing.lifecycle"),
@@ -497,41 +296,86 @@ export const editorRuntimeEventSchema = z.discriminatedUnion("kind", [
     timestampMs: z.int(),
     payload: translationLifecycleRuntimePayloadSchema,
   }),
-  z.strictObject({
-    version: z.literal(1),
-    kind: z.literal("runtime.error"),
-    entityType: runtimeEntityTypeSchema,
-    entityId: z.string().check(z.minLength(1)),
-    locale: z.optional(z.string()),
-    correlationId: z.optional(z.string()),
-    sequence: z.optional(z.int()),
-    timestampMs: z.int(),
-    payload: z.strictObject({
-      code: z.string().check(z.minLength(1)),
-      message: z.string(),
-      retryable: z.optional(z.boolean()),
-      source: z.optional(z.enum(["backend", "collab", "worker"])),
-      details: z.optional(
-        z.record(
-          z.string(),
-          z.union([z.string(), z.number(), z.boolean(), z.null()]),
-        ),
-      ),
-    }),
-  }),
 ]);
 
 export function parseEditorRuntimeEventMessage(
   payload: string,
 ): EditorRuntimeEvent | null {
   try {
-    const data = JSON.parse(payload) as unknown;
-    const result = editorRuntimeEventSchema.safeParse(data);
-    if (!result.success) {
-      return null;
-    }
-    return result.data as EditorRuntimeEvent;
+    const result = editorRuntimeEventSchema.safeParse(JSON.parse(payload));
+    return result.success ? result.data : null;
   } catch {
     return null;
   }
 }
+
+// ---- Types: inferred from the schemas above, the single definition of every runtime event ----
+
+export type RuntimeEntityType = z.infer<typeof runtimeEntityTypeSchema>;
+export type TranslationLifecycleRuntimeStatus = z.infer<
+  typeof translationLifecycleRuntimeStatusSchema
+>;
+export type MediaProcessingRuntimeStatus = z.infer<
+  typeof mediaProcessingRuntimeStatusSchema
+>;
+export type OgGenerationRuntimeEntityType = z.infer<
+  typeof ogGenerationRuntimeEntityTypeSchema
+>;
+export type OgGenerationRuntimeStatus = z.infer<
+  typeof ogGenerationRuntimeStatusSchema
+>;
+export type FileIngestRuntimeSource = z.infer<
+  typeof fileIngestRuntimeSourceSchema
+>;
+export type FileIngestRuntimeStage = z.infer<
+  typeof fileIngestRuntimeStageSchema
+>;
+export type OgGenerationLifecycleRuntimePayload = z.infer<
+  typeof ogGenerationLifecycleRuntimePayloadSchema
+>;
+export type MediaProcessingRuntimeOutputs = z.infer<
+  typeof mediaProcessingRuntimeOutputsSchema
+>;
+export type MediaProcessingLifecycleRuntimePayload = z.infer<
+  typeof mediaProcessingLifecycleRuntimePayloadSchema
+>;
+export type FileIngestLifecycleRuntimePayload = z.infer<
+  typeof fileIngestLifecycleRuntimePayloadSchema
+>;
+export type TranslationLifecycleRuntimePayload = z.infer<
+  typeof translationLifecycleRuntimePayloadSchema
+>;
+export type EditorRuntimeEvent = z.infer<typeof editorRuntimeEventSchema>;
+export type OgGenerationLifecycleRuntimeEvent = Extract<
+  EditorRuntimeEvent,
+  { kind: "og.lifecycle" }
+>;
+export type MediaProcessingLifecycleRuntimeEvent = Extract<
+  EditorRuntimeEvent,
+  { kind: "media.processing.lifecycle" }
+>;
+export type FileIngestLifecycleRuntimeEvent = Extract<
+  EditorRuntimeEvent,
+  { kind: "file.ingest.lifecycle" }
+>;
+export type TranslationLifecycleRuntimeEvent = Extract<
+  EditorRuntimeEvent,
+  { kind: "translation.lifecycle" }
+>;
+
+export function isMediaProcessingRuntimeReady(payload: {
+  status?: MediaProcessingRuntimeStatus | null;
+}): boolean {
+  return payload.status === "ready";
+}
+
+export function isOgGenerationRuntimeTerminal(
+  status: OgGenerationRuntimeStatus,
+): boolean {
+  return (
+    status === "ready" ||
+    status === "failed" ||
+    status === "superseded" ||
+    status === "cancelled"
+  );
+}