@dogmatiq/protobuf 0.5.0 → 0.6.0

package/README.md

@@ -30,12 +30,12 @@ import "github.com/dogmatiq/protobuf/uuidpb/uuid.proto";
 
 ## Packages
 
-| Package         | Protocol Buffers package | Contents                      |
-| --------------- | ------------------------ | ----------------------------- |
-| `uuidpb`        | `dogma.protobuf.v1`      | `UUID`                        |
-| `identitypb`    | `dogma.protobuf.v1`      | `Identity`                    |
-| `envelopepb`    | `dogma.protobuf.v1`      | `Envelope` and extensions     |
-| `messaginggrpc` | `dogma.messaging.v1`     | The event stream consumer API |
+| Package         | Protocol Buffers package | Contents                                   |
+| --------------- | ------------------------ | ------------------------------------------ |
+| `uuidpb`        | `dogma.protobuf.v1`      | `UUID`                                     |
+| `identitypb`    | `dogma.protobuf.v1`      | `Identity`                                 |
+| `envelopepb`    | `dogma.protobuf.v1`      | `Envelope`, `MultiEnvelope` and extensions |
+| `messaginggrpc` | `dogma.messaging.v1`     | The event stream consumer API              |
 
 ## Message data
 

package/artifacts/dist/envelopepb/envelope.d.ts

@@ -1,4 +1,28 @@
-import type { Body, Envelope, Header, Message } from "./envelope_pb.js";
+import { type Body, type Envelope, type Header, type Message, type MultiEnvelope } from "./envelope_pb.js";
+/**
+ * Returns each message in a {@link MultiEnvelope} as a standalone
+ * {@link Envelope}.
+ *
+ * The returned envelopes share the multi-envelope's header.
+ */
+export declare function expandMultiEnvelope(x: MultiEnvelope): Envelope[];
+/**
+ * Returns a {@link MultiEnvelope} that contains the same header and body as
+ * env.
+ *
+ * The multi-envelope shares the envelope's header and body.
+ *
+ * @throws {Error} If env has no body.
+ */
+export declare function asMultiEnvelope(env: Envelope): MultiEnvelope;
+/**
+ * Appends the body of env to x if they have equivalent headers.
+ *
+ * It returns false, and does not modify x, if the headers differ.
+ *
+ * @throws {Error} If env has no body.
+ */
+export declare function tryAppendEnvelope(x: MultiEnvelope, env: Envelope): boolean;
 /**
  * Throws an error if env is not well-formed.
  *
@@ -11,6 +35,12 @@ import type { Body, Envelope, Header, Message } from "./envelope_pb.js";
  * data can be decoded.
  */
 export declare function validateEnvelope(env: Envelope): void;
+/**
+ * Throws an error if x is not well-formed.
+ *
+ * See {@link validateEnvelope} for what well-formedness means.
+ */
+export declare function validateMultiEnvelope(x: MultiEnvelope): void;
 /**
  * Throws an error if x is not well-formed.
  *

package/artifacts/dist/envelopepb/envelope.js

@@ -1,8 +1,55 @@
-import { create } from "@bufbuild/protobuf";
+import { create, createRegistry, equals } from "@bufbuild/protobuf";
 import { IdentitySchema } from "../identitypb/identity_pb.js";
 import { identityToString, validateIdentity } from "../identitypb/identity.js";
 import { UUIDSchema } from "../uuidpb/uuid_pb.js";
 import { uuidToString, validateUUID } from "../uuidpb/uuid.js";
+import { EnvelopeSchema, HeaderSchema, MultiEnvelopeSchema, } from "./envelope_pb.js";
+/**
+ * Returns each message in a {@link MultiEnvelope} as a standalone
+ * {@link Envelope}.
+ *
+ * The returned envelopes share the multi-envelope's header.
+ */
+export function expandMultiEnvelope(x) {
+    return x.bodies.map((body) => create(EnvelopeSchema, { header: x.header, body }));
+}
+/**
+ * Returns a {@link MultiEnvelope} that contains the same header and body as
+ * env.
+ *
+ * The multi-envelope shares the envelope's header and body.
+ *
+ * @throws {Error} If env has no body.
+ */
+export function asMultiEnvelope(env) {
+    if (!env.body) {
+        throw new Error("envelope must have a body");
+    }
+    return create(MultiEnvelopeSchema, {
+        header: env.header,
+        bodies: [env.body],
+    });
+}
+/**
+ * Appends the body of env to x if they have equivalent headers.
+ *
+ * It returns false, and does not modify x, if the headers differ.
+ *
+ * @throws {Error} If env has no body.
+ */
+export function tryAppendEnvelope(x, env) {
+    if (!env.body) {
+        throw new Error("envelope must have a body");
+    }
+    const a = x.header;
+    const b = env.header;
+    const same = a && b ? headersEqual(a, b) : a === b;
+    if (!same) {
+        return false;
+    }
+    x.bodies.push(env.body);
+    return true;
+}
 /**
  * Throws an error if env is not well-formed.
  *
@@ -18,6 +65,15 @@ export function validateEnvelope(env) {
     check("invalid header", () => validateHeader(env.header));
     check("invalid body", () => validateBody(env.body, env.header));
 }
+/**
+ * Throws an error if x is not well-formed.
+ *
+ * See {@link validateEnvelope} for what well-formedness means.
+ */
+export function validateMultiEnvelope(x) {
+    check("invalid header", () => validateHeader(x.header));
+    x.bodies.forEach((body, i) => check(`invalid body at index ${i}`, () => validateBody(body, x.header)));
+}
 /**
  * Throws an error if x is not well-formed.
  *
@@ -140,3 +196,20 @@ function check(prefix, fn) {
         throw new Error(`${prefix}: ${cause.message}`, { cause });
     }
 }
+// headersEqual returns true if a and b are equivalent, including any unknown
+// fields, as Go's proto.Equal() does. The equals() function from protobuf-es
+// ignores unknown fields unless the "unknown" option is set.
+//
+// Unlike proto.Equal(), it compares unknown fields in the order they were
+// decoded, rather than grouped by field number, so headers whose unknown fields
+// arrived in a different order are not equal.
+//
+// The "unknown" option is marked as experimental by protobuf-es, so it may
+// change in a later release. A test covers it, so that such a change is
+// noticed.
+function headersEqual(a, b) {
+    return equals(HeaderSchema, a, b, { registry: REGISTRY, unknown: true });
+}
+// REGISTRY is the registry passed to equals(). It's empty because Header has no
+// extensions, so every unknown field is genuinely unknown.
+const REGISTRY = createRegistry();

package/artifacts/dist/envelopepb/envelope_pb.d.ts

@@ -10,6 +10,10 @@ export declare const file_github_com_dogmatiq_protobuf_envelopepb_envelope: GenF
 /**
  * Envelope is a container for a Dogma message and its meta-data.
  *
+ * An Envelope can be decoded as a single-body [MultiEnvelope]. Decoding a
+ * MultiEnvelope as an Envelope is only safe when it contains exactly one body;
+ * multiple bodies merge when decoded into the singular body field.
+ *
  * @generated from message dogma.protobuf.v1.Envelope
  */
 export type Envelope = Message$1<"dogma.protobuf.v1.Envelope"> & {
@@ -27,6 +31,27 @@ export type Envelope = Message$1<"dogma.protobuf.v1.Envelope"> & {
  * Use `create(EnvelopeSchema)` to create a new message.
  */
 export declare const EnvelopeSchema: GenMessage<Envelope>;
+/**
+ * MultiEnvelope is an efficient encoding of an ordered sequence of [Envelope]
+ * values that share common header context.
+ *
+ * @generated from message dogma.protobuf.v1.MultiEnvelope
+ */
+export type MultiEnvelope = Message$1<"dogma.protobuf.v1.MultiEnvelope"> & {
+    /**
+     * @generated from field: dogma.protobuf.v1.Header header = 1;
+     */
+    header?: Header | undefined;
+    /**
+     * @generated from field: repeated dogma.protobuf.v1.Body bodies = 2;
+     */
+    bodies: Body[];
+};
+/**
+ * Describes the message dogma.protobuf.v1.MultiEnvelope.
+ * Use `create(MultiEnvelopeSchema)` to create a new message.
+ */
+export declare const MultiEnvelopeSchema: GenMessage<MultiEnvelope>;
 /**
  * Source identifies where a message originated.
  *
@@ -127,7 +152,7 @@ export declare const MessageSchema: GenMessage<Message>;
 export type Header = Message$1<"dogma.protobuf.v1.Header"> & {
     /**
      * CausationId is the ID of the message that was the direct cause of the
-     * message.
+     * messages.
      *
      * It is required. A message that was not caused by any other message is its
      * own cause, so its causation ID is its own message ID.
@@ -136,9 +161,9 @@ export type Header = Message$1<"dogma.protobuf.v1.Header"> & {
      */
     causationId?: UUID | undefined;
     /**
-     * CorrelationId is the ID of the first ancestor of the message that was
+     * CorrelationId is the ID of the first ancestor of the messages that was
      * itself not caused by another message, that is, it's the root of the message
-     * chain that ultimately resulted in this message.
+     * chain that ultimately resulted in these messages.
      *
      * It is required. A message that was not caused by any other message is the
      * root of its own chain, so its correlation ID is its own message ID.
@@ -147,14 +172,14 @@ export type Header = Message$1<"dogma.protobuf.v1.Header"> & {
      */
     correlationId?: UUID | undefined;
     /**
-     * Source identifies the origin of the message.
+     * Source identifies the origin of the messages.
      *
      * @generated from field: dogma.protobuf.v1.Source source = 3;
      */
     source?: Source | undefined;
     /**
-     * Extensions is a set of extension values associated with the message,
-     * its causal chain, or the envelope itself.
+     * Extensions is a set of extension values associated with the messages,
+     * their causal chain, or the envelope itself.
      *
      * @generated from field: repeated google.protobuf.Any extensions = 4;
      */
@@ -174,7 +199,7 @@ export type Header = Message$1<"dogma.protobuf.v1.Header"> & {
 export declare const HeaderSchema: GenMessage<Header>;
 /**
  * Body contains the metadata and encoded form of a single message in an
- * [Envelope].
+ * [Envelope] or [MultiEnvelope].
  *
  * @generated from message dogma.protobuf.v1.Body
  */

package/artifacts/dist/envelopepb/envelope_pb.js

@@ -8,29 +8,34 @@ import { file_github_com_dogmatiq_protobuf_uuidpb_uuid } from "../uuidpb/uuid_pb
 /**
  * Describes the file github.com/dogmatiq/protobuf/envelopepb/envelope.proto.
  */
-export const file_github_com_dogmatiq_protobuf_envelopepb_envelope = /*@__PURE__*/ fileDesc("CjZnaXRodWIuY29tL2RvZ21hdGlxL3Byb3RvYnVmL2VudmVsb3BlcGIvZW52ZWxvcGUucHJvdG8SEWRvZ21hLnByb3RvYnVmLnYxIlwKCEVudmVsb3BlEikKBmhlYWRlchgBIAEoCzIZLmRvZ21hLnByb3RvYnVmLnYxLkhlYWRlchIlCgRib2R5GAIgASgLMhcuZG9nbWEucHJvdG9idWYudjEuQm9keSKvAQoGU291cmNlEikKBHNpdGUYASABKAsyGy5kb2dtYS5wcm90b2J1Zi52MS5JZGVudGl0eRIwCgthcHBsaWNhdGlvbhgCIAEoCzIbLmRvZ21hLnByb3RvYnVmLnYxLklkZW50aXR5EiwKB2hhbmRsZXIYAyABKAsyGy5kb2dtYS5wcm90b2J1Zi52MS5JZGVudGl0eRIaCgtpbnN0YW5jZV9pZBgEIAEoCUIFqgECCAIiZAoHTWVzc2FnZRIoCgd0eXBlX2lkGAEgASgLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJRBIaCgtkZXNjcmlwdGlvbhgCIAEoCUIFqgECCAISEwoEZGF0YRgDIAEoDEIFqgECCAIi5AEKBkhlYWRlchItCgxjYXVzYXRpb25faWQYASABKAsyFy5kb2dtYS5wcm90b2J1Zi52MS5VVUlEEi8KDmNvcnJlbGF0aW9uX2lkGAIgASgLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJRBIpCgZzb3VyY2UYAyABKAsyGS5kb2dtYS5wcm90b2J1Zi52MS5Tb3VyY2USKAoKZXh0ZW5zaW9ucxgEIAMoCzIULmdvb2dsZS5wcm90b2J1Zi5BbnkSJQoHYmFnZ2FnZRgFIAMoCzIULmdvb2dsZS5wcm90b2J1Zi5BbnkitAIKBEJvZHkSKwoKbWVzc2FnZV9pZBgBIAEoCzIXLmRvZ21hLnByb3RvYnVmLnYxLlVVSUQSHgoPaWRlbXBvdGVuY3lfa2V5GAIgASgJQgWqAQIIAhIuCgpjcmVhdGVkX2F0GAMgASgLMhouZ29vZ2xlLnByb3RvYnVmLlRpbWVzdGFtcBIxCg1zY2hlZHVsZWRfZm9yGAQgASgLMhouZ29vZ2xlLnByb3RvYnVmLlRpbWVzdGFtcBIrCgdtZXNzYWdlGAUgASgLMhouZG9nbWEucHJvdG9idWYudjEuTWVzc2FnZRIoCgpleHRlbnNpb25zGAYgAygLMhQuZ29vZ2xlLnByb3RvYnVmLkFueRIlCgdiYWdnYWdlGAcgAygLMhQuZ29vZ2xlLnByb3RvYnVmLkFueUIpWidnaXRodWIuY29tL2RvZ21hdGlxL3Byb3RvYnVmL2VudmVsb3BlcGJiCGVkaXRpb25zcOkH", [file_google_protobuf_timestamp, file_google_protobuf_any, file_github_com_dogmatiq_protobuf_identitypb_identity, file_github_com_dogmatiq_protobuf_uuidpb_uuid]);
+export const file_github_com_dogmatiq_protobuf_envelopepb_envelope = /*@__PURE__*/ fileDesc("CjZnaXRodWIuY29tL2RvZ21hdGlxL3Byb3RvYnVmL2VudmVsb3BlcGIvZW52ZWxvcGUucHJvdG8SEWRvZ21hLnByb3RvYnVmLnYxIlwKCEVudmVsb3BlEikKBmhlYWRlchgBIAEoCzIZLmRvZ21hLnByb3RvYnVmLnYxLkhlYWRlchIlCgRib2R5GAIgASgLMhcuZG9nbWEucHJvdG9idWYudjEuQm9keSJjCg1NdWx0aUVudmVsb3BlEikKBmhlYWRlchgBIAEoCzIZLmRvZ21hLnByb3RvYnVmLnYxLkhlYWRlchInCgZib2RpZXMYAiADKAsyFy5kb2dtYS5wcm90b2J1Zi52MS5Cb2R5Iq8BCgZTb3VyY2USKQoEc2l0ZRgBIAEoCzIbLmRvZ21hLnByb3RvYnVmLnYxLklkZW50aXR5EjAKC2FwcGxpY2F0aW9uGAIgASgLMhsuZG9nbWEucHJvdG9idWYudjEuSWRlbnRpdHkSLAoHaGFuZGxlchgDIAEoCzIbLmRvZ21hLnByb3RvYnVmLnYxLklkZW50aXR5EhoKC2luc3RhbmNlX2lkGAQgASgJQgWqAQIIAiJkCgdNZXNzYWdlEigKB3R5cGVfaWQYASABKAsyFy5kb2dtYS5wcm90b2J1Zi52MS5VVUlEEhoKC2Rlc2NyaXB0aW9uGAIgASgJQgWqAQIIAhITCgRkYXRhGAMgASgMQgWqAQIIAiLkAQoGSGVhZGVyEi0KDGNhdXNhdGlvbl9pZBgBIAEoCzIXLmRvZ21hLnByb3RvYnVmLnYxLlVVSUQSLwoOY29ycmVsYXRpb25faWQYAiABKAsyFy5kb2dtYS5wcm90b2J1Zi52MS5VVUlEEikKBnNvdXJjZRgDIAEoCzIZLmRvZ21hLnByb3RvYnVmLnYxLlNvdXJjZRIoCgpleHRlbnNpb25zGAQgAygLMhQuZ29vZ2xlLnByb3RvYnVmLkFueRIlCgdiYWdnYWdlGAUgAygLMhQuZ29vZ2xlLnByb3RvYnVmLkFueSK0AgoEQm9keRIrCgptZXNzYWdlX2lkGAEgASgLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJRBIeCg9pZGVtcG90ZW5jeV9rZXkYAiABKAlCBaoBAggCEi4KCmNyZWF0ZWRfYXQYAyABKAsyGi5nb29nbGUucHJvdG9idWYuVGltZXN0YW1wEjEKDXNjaGVkdWxlZF9mb3IYBCABKAsyGi5nb29nbGUucHJvdG9idWYuVGltZXN0YW1wEisKB21lc3NhZ2UYBSABKAsyGi5kb2dtYS5wcm90b2J1Zi52MS5NZXNzYWdlEigKCmV4dGVuc2lvbnMYBiADKAsyFC5nb29nbGUucHJvdG9idWYuQW55EiUKB2JhZ2dhZ2UYByADKAsyFC5nb29nbGUucHJvdG9idWYuQW55QilaJ2dpdGh1Yi5jb20vZG9nbWF0aXEvcHJvdG9idWYvZW52ZWxvcGVwYmIIZWRpdGlvbnNw6Qc", [file_google_protobuf_timestamp, file_google_protobuf_any, file_github_com_dogmatiq_protobuf_identitypb_identity, file_github_com_dogmatiq_protobuf_uuidpb_uuid]);
 /**
  * Describes the message dogma.protobuf.v1.Envelope.
  * Use `create(EnvelopeSchema)` to create a new message.
  */
 export const EnvelopeSchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_envelopepb_envelope, 0);
+/**
+ * Describes the message dogma.protobuf.v1.MultiEnvelope.
+ * Use `create(MultiEnvelopeSchema)` to create a new message.
+ */
+export const MultiEnvelopeSchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_envelopepb_envelope, 1);
 /**
  * Describes the message dogma.protobuf.v1.Source.
  * Use `create(SourceSchema)` to create a new message.
  */
-export const SourceSchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_envelopepb_envelope, 1);
+export const SourceSchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_envelopepb_envelope, 2);
 /**
  * Describes the message dogma.protobuf.v1.Message.
  * Use `create(MessageSchema)` to create a new message.
  */
-export const MessageSchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_envelopepb_envelope, 2);
+export const MessageSchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_envelopepb_envelope, 3);
 /**
  * Describes the message dogma.protobuf.v1.Header.
  * Use `create(HeaderSchema)` to create a new message.
  */
-export const HeaderSchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_envelopepb_envelope, 3);
+export const HeaderSchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_envelopepb_envelope, 4);
 /**
  * Describes the message dogma.protobuf.v1.Body.
  * Use `create(BodySchema)` to create a new message.
  */
-export const BodySchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_envelopepb_envelope, 4);
+export const BodySchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_envelopepb_envelope, 5);

package/artifacts/dist/messaginggrpc/eventstreamconsumer_pb.d.ts

@@ -1,5 +1,5 @@
 import type { GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv2";
-import type { Envelope } from "../envelopepb/envelope_pb.js";
+import type { MultiEnvelope } from "../envelopepb/envelope_pb.js";
 import type { UUID } from "../uuidpb/uuid_pb.js";
 import type { MessageFilter } from "./filter_pb.js";
 import type { Message } from "@bufbuild/protobuf";
@@ -92,18 +92,19 @@ export type EventStreamSegment = Message<"dogma.messaging.v1.EventStreamSegment"
      */
     endOffset: bigint;
     /**
-     * Envelopes is a (possibly empty) list of envelopes containing the
+     * Envelopes is a (possibly empty) list of multi-envelopes containing the
      * events in the range that match the requested message types.
      *
      * Each envelope includes the [envelopepb.EventStreamPosition] extension.
      *
-     * The events appear in ascending offset order. Their offsets may have gaps,
-     * because events of other types are omitted. There is no additional
-     * relationship implied between envelopes that appear in the same segment.
+     * The events appear in ascending offset order, both within each
+     * multi-envelope and across the list. Their offsets may have gaps, because
+     * events of other types are omitted. There is no additional relationship
+     * implied between envelopes that appear in the same segment.
      *
-     * @generated from field: repeated dogma.protobuf.v1.Envelope envelopes = 4;
+     * @generated from field: repeated dogma.protobuf.v1.MultiEnvelope envelopes = 4;
      */
-    envelopes: Envelope[];
+    envelopes: MultiEnvelope[];
 };
 /**
  * Describes the message dogma.messaging.v1.EventStreamSegment.

package/artifacts/dist/messaginggrpc/eventstreamconsumer_pb.js

@@ -8,7 +8,7 @@ import { file_github_com_dogmatiq_protobuf_messaginggrpc_filter } from "./filter
 /**
  * Describes the file github.com/dogmatiq/protobuf/messaginggrpc/eventstreamconsumer.proto.
  */
-export const file_github_com_dogmatiq_protobuf_messaginggrpc_eventstreamconsumer = /*@__PURE__*/ fileDesc("CkRnaXRodWIuY29tL2RvZ21hdGlxL3Byb3RvYnVmL21lc3NhZ2luZ2dycGMvZXZlbnRzdHJlYW1jb25zdW1lci5wcm90bxISZG9nbWEubWVzc2FnaW5nLnYxIkcKEldhdGNoRXZlbnRzUmVxdWVzdBIxCgZmaWx0ZXIYASABKAsyIS5kb2dtYS5tZXNzYWdpbmcudjEuTWVzc2FnZUZpbHRlciKVAQoRUmVhZEV2ZW50c1JlcXVlc3QSMAoPZXZlbnRfc3RyZWFtX2lkGAEgASgLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJRBIbCgxiZWdpbl9vZmZzZXQYAiABKARCBaoBAggCEjEKBmZpbHRlchgDIAEoCzIhLmRvZ21hLm1lc3NhZ2luZy52MS5NZXNzYWdlRmlsdGVyIq4BChJFdmVudFN0cmVhbVNlZ21lbnQSMAoPZXZlbnRfc3RyZWFtX2lkGAEgASgLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJRBIbCgxiZWdpbl9vZmZzZXQYAiABKARCBaoBAggCEhkKCmVuZF9vZmZzZXQYAyABKARCBaoBAggCEi4KCWVudmVsb3BlcxgEIAMoCzIbLmRvZ21hLnByb3RvYnVmLnYxLkVudmVsb3BlMtgBChZFdmVudFN0cmVhbUNvbnN1bWVyQVBJEl8KC1dhdGNoRXZlbnRzEiYuZG9nbWEubWVzc2FnaW5nLnYxLldhdGNoRXZlbnRzUmVxdWVzdBomLmRvZ21hLm1lc3NhZ2luZy52MS5FdmVudFN0cmVhbVNlZ21lbnQwARJdCgpSZWFkRXZlbnRzEiUuZG9nbWEubWVzc2FnaW5nLnYxLlJlYWRFdmVudHNSZXF1ZXN0GiYuZG9nbWEubWVzc2FnaW5nLnYxLkV2ZW50U3RyZWFtU2VnbWVudDABQixaKmdpdGh1Yi5jb20vZG9nbWF0aXEvcHJvdG9idWYvbWVzc2FnaW5nZ3JwY2IIZWRpdGlvbnNw6Qc", [file_github_com_dogmatiq_protobuf_envelopepb_envelope, file_github_com_dogmatiq_protobuf_uuidpb_uuid, file_github_com_dogmatiq_protobuf_messaginggrpc_filter]);
+export const file_github_com_dogmatiq_protobuf_messaginggrpc_eventstreamconsumer = /*@__PURE__*/ fileDesc("CkRnaXRodWIuY29tL2RvZ21hdGlxL3Byb3RvYnVmL21lc3NhZ2luZ2dycGMvZXZlbnRzdHJlYW1jb25zdW1lci5wcm90bxISZG9nbWEubWVzc2FnaW5nLnYxIkcKEldhdGNoRXZlbnRzUmVxdWVzdBIxCgZmaWx0ZXIYASABKAsyIS5kb2dtYS5tZXNzYWdpbmcudjEuTWVzc2FnZUZpbHRlciKVAQoRUmVhZEV2ZW50c1JlcXVlc3QSMAoPZXZlbnRfc3RyZWFtX2lkGAEgASgLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJRBIbCgxiZWdpbl9vZmZzZXQYAiABKARCBaoBAggCEjEKBmZpbHRlchgDIAEoCzIhLmRvZ21hLm1lc3NhZ2luZy52MS5NZXNzYWdlRmlsdGVyIrMBChJFdmVudFN0cmVhbVNlZ21lbnQSMAoPZXZlbnRfc3RyZWFtX2lkGAEgASgLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJRBIbCgxiZWdpbl9vZmZzZXQYAiABKARCBaoBAggCEhkKCmVuZF9vZmZzZXQYAyABKARCBaoBAggCEjMKCWVudmVsb3BlcxgEIAMoCzIgLmRvZ21hLnByb3RvYnVmLnYxLk11bHRpRW52ZWxvcGUy2AEKFkV2ZW50U3RyZWFtQ29uc3VtZXJBUEkSXwoLV2F0Y2hFdmVudHMSJi5kb2dtYS5tZXNzYWdpbmcudjEuV2F0Y2hFdmVudHNSZXF1ZXN0GiYuZG9nbWEubWVzc2FnaW5nLnYxLkV2ZW50U3RyZWFtU2VnbWVudDABEl0KClJlYWRFdmVudHMSJS5kb2dtYS5tZXNzYWdpbmcudjEuUmVhZEV2ZW50c1JlcXVlc3QaJi5kb2dtYS5tZXNzYWdpbmcudjEuRXZlbnRTdHJlYW1TZWdtZW50MAFCLFoqZ2l0aHViLmNvbS9kb2dtYXRpcS9wcm90b2J1Zi9tZXNzYWdpbmdncnBjYghlZGl0aW9uc3DpBw", [file_github_com_dogmatiq_protobuf_envelopepb_envelope, file_github_com_dogmatiq_protobuf_uuidpb_uuid, file_github_com_dogmatiq_protobuf_messaginggrpc_filter]);
 /**
  * Describes the message dogma.messaging.v1.WatchEventsRequest.
  * Use `create(WatchEventsRequestSchema)` to create a new message.

package/envelopepb/envelope.proto

@@ -9,11 +9,22 @@ import "github.com/dogmatiq/protobuf/identitypb/identity.proto";
 import "github.com/dogmatiq/protobuf/uuidpb/uuid.proto";
 
 // Envelope is a container for a Dogma message and its meta-data.
+//
+// An Envelope can be decoded as a single-body [MultiEnvelope]. Decoding a
+// MultiEnvelope as an Envelope is only safe when it contains exactly one body;
+// multiple bodies merge when decoded into the singular body field.
 message Envelope {
   Header header = 1;
   Body   body   = 2;
 }
 
+// MultiEnvelope is an efficient encoding of an ordered sequence of [Envelope]
+// values that share common header context.
+message MultiEnvelope {
+  Header        header = 1;
+  repeated Body bodies = 2;
+}
+
 // Source identifies where a message originated.
 message Source {
   // Site is the (optional) identity of the "site" that the source
@@ -70,25 +81,25 @@ message Message {
 // type. Body values take precedence over header values of the same type.
 message Header {
   // CausationId is the ID of the message that was the direct cause of the
-  // message.
+  // messages.
   //
   // It is required. A message that was not caused by any other message is its
   // own cause, so its causation ID is its own message ID.
   UUID causation_id = 1;
 
-  // CorrelationId is the ID of the first ancestor of the message that was
+  // CorrelationId is the ID of the first ancestor of the messages that was
   // itself not caused by another message, that is, it's the root of the message
-  // chain that ultimately resulted in this message.
+  // chain that ultimately resulted in these messages.
   //
   // It is required. A message that was not caused by any other message is the
   // root of its own chain, so its correlation ID is its own message ID.
   UUID correlation_id = 2;
 
-  // Source identifies the origin of the message.
+  // Source identifies the origin of the messages.
   Source source = 3;
 
-  // Extensions is a set of extension values associated with the message,
-  // its causal chain, or the envelope itself.
+  // Extensions is a set of extension values associated with the messages,
+  // their causal chain, or the envelope itself.
   repeated google.protobuf.Any extensions = 4;
 
   // Baggage is a set of extension values that are propagated through the
@@ -97,7 +108,7 @@ message Header {
 }
 
 // Body contains the metadata and encoded form of a single message in an
-// [Envelope].
+// [Envelope] or [MultiEnvelope].
 message Body {
   // MessageId is a unique identifier for the message in this envelope.
   UUID message_id = 1;

package/messaginggrpc/eventstreamconsumer.proto

@@ -86,13 +86,14 @@ message EventStreamSegment {
   // EndOffset is the offset immediately after the range, exclusive.
   uint64 end_offset = 3 [features.field_presence = IMPLICIT];
 
-  // Envelopes is a (possibly empty) list of envelopes containing the
+  // Envelopes is a (possibly empty) list of multi-envelopes containing the
   // events in the range that match the requested message types.
   //
   // Each envelope includes the [envelopepb.EventStreamPosition] extension.
   //
-  // The events appear in ascending offset order. Their offsets may have gaps,
-  // because events of other types are omitted. There is no additional
-  // relationship implied between envelopes that appear in the same segment.
-  repeated dogma.protobuf.v1.Envelope envelopes = 4;
+  // The events appear in ascending offset order, both within each
+  // multi-envelope and across the list. Their offsets may have gaps, because
+  // events of other types are omitted. There is no additional relationship
+  // implied between envelopes that appear in the same segment.
+  repeated dogma.protobuf.v1.MultiEnvelope envelopes = 4;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogmatiq/protobuf",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Protocol Buffers and gRPC definitions for Dogma",
   "keywords": [
     "dogma",