@spine-event-engine/proto 2.0.0-snapshot.10

package/proto/spine/server/catchup/catch_up.proto

@@ -0,0 +1,123 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+syntax = "proto3";
+
+package spine.server.catchup;
+
+import "spine/options.proto";
+import "spine/time_options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option java_package = "io.spine.server.delivery";
+option java_outer_classname = "CatchUpProto";
+option java_multiple_files = true;
+
+import "google/protobuf/any.proto";
+import "google/protobuf/timestamp.proto";
+
+import "spine/core/event.proto";
+
+// A state of a catch-up process.
+message CatchUp {
+    option (is).java_type = "CatchUpMixin";
+
+    CatchUpId id = 1;
+
+    // A description of a catch-up requested.
+    message Request {
+
+        // IDs of the projections under catch-up, packed as `Any`.
+        //
+        // If no particular targets are set, the catch-up is requested for all entities
+        // of the respective kind.
+        //
+        repeated google.protobuf.Any target = 1;
+
+        // Since which point in time the catch-up has been originally requested.
+        //
+        // This value is inclusive of the timestamp of events to which this catch-up should
+        // be applicable.
+        //
+        google.protobuf.Timestamp since_when = 2 [(required) = true, (when).in = PAST];
+
+        // The type URLs of events to read from the Event Store.
+        repeated string event_type = 3;
+    }
+
+    // The original request.
+    Request request = 2 [(required) = true, (validate) = true];
+
+    // During the catch-up, this field holds the timestamp of the last event already processed.
+    google.protobuf.Timestamp when_last_read = 3;
+
+    // The current status of the catch-up process.
+    CatchUpStatus status = 4 [(required) = true];
+
+    // The total number of shards in the environment
+    // at the moment of the last dispatching of the historical messages.
+    //
+    int32 total_shards = 5;
+
+    // The indexes of the shards through which the historical messages were dispatched.
+    repeated int32 affected_shard = 6;
+
+    // The number of target projection instances whose state has to be cleared before
+    // the historical events start being recalled.
+    //
+    int32 instances_to_clear = 7;
+
+    // The indexes of shards in which the dispatching of the catch-up events is finalized.
+    repeated int32 finalized_shard = 8;
+}
+
+// An ID of a catch-up process.
+message CatchUpId {
+
+    string uuid = 1;
+
+    // A type URL of the projection under catch-up.
+    string projection_type = 2 [(required) = true];
+}
+
+// The status of a catch-up process.
+enum CatchUpStatus {
+
+    // Not started.
+    CUS_UNDEFINED = 0;
+
+    // The process has been started.
+    STARTED = 1;
+
+    // The process has been started and is in progress.
+    IN_PROGRESS = 2;
+
+    // The process is now processing the events that are close to the current time.
+    FINALIZING = 3;
+
+    // The process is completed.
+    COMPLETED = 4;
+}

package/proto/spine/server/delivery/delivery.proto

@@ -0,0 +1,166 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+syntax = "proto3";
+
+package spine.server.delivery;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option (internal_all) = true;
+
+option java_package = "io.spine.server.delivery";
+option java_outer_classname = "DeliveryProto";
+option java_multiple_files = true;
+
+import "google/protobuf/timestamp.proto";
+
+import "spine/server/server_environment.proto";
+import "spine/server/catchup/catch_up.proto";
+
+// An index of a shard.
+//
+// A value type used across the application. To be potentially used in JavaScript, Go, C++ and
+// other client and server environments that are split into shards.
+//
+message ShardIndex {
+
+    // The zero-based index of the shard.
+    int32 index = 1 [(min).value = "0"];
+
+    // Total number of shards.
+    int32 of_total = 2 [(min).value = "1"];
+}
+
+// A record describing the session in scope of which sharded messages are being processed.
+message ShardSessionRecord {
+
+    // The index of a shard processed in this session.
+    ShardIndex index = 1 [(required) = true];
+
+    // When the shard processed within the session was last picked up by the node.
+    //
+    // This field is unset if no nodes ever picked up the session.
+    //
+    google.protobuf.Timestamp when_last_picked = 3;
+
+    // An identifier of an application worker, which picked up the shard and processes it.
+    //
+    // Unset until a worker picks the shard.
+    //
+    WorkerId worker = 4;
+
+    reserved 2;
+    reserved "picked_by";
+}
+
+// A stage of the `Delivery` process running for some particular `ShardIndex`.
+message DeliveryStage {
+
+    // The index of a shard for which the delivery stage was performed.
+    ShardIndex index = 1 [(required) = true, (validate) = true];
+
+    // How many messages were delivered in scope of this stage.
+    int32 messagesDelivered = 2 [(min).value = "0"];
+}
+
+// A process performing the maintenance of the shard with its messages.
+//
+// Represented in each of the bounded contexts as an event reactor,
+// as it's impossible to have several process managers of the same state across bounded contexts.
+message ShardMaintenance {
+
+    ShardIndex id = 1;
+}
+
+// The configuration data `Delivery` used at its run-time to make decisions on how
+// to dispatch messages.
+//
+// The system-wide processes, such as `CatchUp`, need to know the details on how the messages
+// were dispatched by `Delivery`. Therefore, `Delivery` records some of its parameters
+// when it is delivering the signals, and passes this data on to all interested parties.
+//
+message DeliveryRunInfo {
+
+    // The catch-up jobs observed by the Delivery.
+    repeated catchup.CatchUp catch_up_job = 1;
+}
+
+// An identifier of a worker that processes a shard.
+//
+// This value is unique across the application. It is used to indicate who is currently processing
+// which shard. A single node can contain several workers (typically represented by threads)
+// processing different shards.
+message WorkerId {
+
+    // A node to which this worker belongs.
+    NodeId nodeId = 1 [(required) = true];
+
+    // Worker's identifier.
+    //
+    // An example of such an identifier could be the ID of the thread that processes a shard.
+    string value = 2 [(required) = true];
+}
+
+// An outcome of a shard pick-up request, stating that the shard is already picked up
+// by another worker.
+message ShardAlreadyPickedUp {
+
+    // A worker that owns the session at the moment.
+    WorkerId worker = 1 [(required) = true];
+
+    // Time when the worker has picked up the shard.
+    //
+    // Note: this value is not synchronized between application servers by default.
+    // The wall clock on each instance is generally slightly different.
+    // Comparing this value (potentially instantiated on another application node)
+    // with the wall clock on your current application node may give
+    // some misleading results.
+    //
+    google.protobuf.Timestamp when_picked = 2 [(required) = true];
+}
+
+// An outcome of a shard pick-up attempt.
+message PickUpOutcome {
+
+    option (is).java_type = "io.spine.server.delivery.PickUpOutcomeMixin";
+
+    oneof value {
+        option (choice).required = true;
+
+        // Shard was picked up successfully, and this value points to the
+        // delivery session owned by the node requested to pick up the shard.
+        ShardSessionRecord session = 1;
+
+        // Shard could not be picked up as it's already picked up by another worker.
+        //
+        // This value brings some additional information about the currently
+        // ongoing session owned by another worker node.
+        //
+        ShardAlreadyPickedUp already_picked = 2;
+    }
+}

package/proto/spine/server/delivery/delivery_events.proto

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+syntax = "proto3";
+
+package spine.server.delivery;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option (internal_all) = true;
+option (every_is).java_type = "io.spine.server.delivery.ShardEvent";
+
+option java_package = "io.spine.server.delivery.event";
+option java_outer_classname = "DeliveryEventsProto";
+option java_multiple_files = true;
+
+import "google/protobuf/any.proto";
+
+import "spine/server/delivery/delivery.proto";
+import "spine/server/catchup/catch_up.proto";
+
+// The processing of the messages in the particular shard was requested by the framework.
+message ShardProcessingRequested {
+
+    ShardIndex index = 1 [(required) = true, (validate) = true];
+
+    // The run-time data of the delivery at the moment when this event has been dispatched.
+    DeliveryRunInfo run_info = 2;
+
+    // An identifier of a `CatchUp` process in scope of which the shard processing
+    // was originally requested.
+    //
+    catchup.CatchUpId process = 3 [(required) = true];
+}
+
+// The processing of the messages in the particular shard was performed.
+message ShardProcessed {
+
+    ShardIndex index = 1 [(required) = true, (validate) = true];
+
+    // The run-time data of the delivery at the moment when the shard was processed.
+    DeliveryRunInfo run_info = 2;
+
+    // An identifier of a `CatchUp` process in scope of which the shard processing
+    // was originally requested.
+    //
+    catchup.CatchUpId process = 3 [(required) = true];
+}

package/proto/spine/server/delivery/inbox.proto

@@ -0,0 +1,169 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+syntax = "proto3";
+
+package spine.server.delivery;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option (internal_all) = true;
+
+option java_package = "io.spine.server.delivery";
+option java_outer_classname = "InboxProto";
+option java_multiple_files = true;
+
+import "google/protobuf/timestamp.proto";
+
+import "spine/client/entities.proto";
+import "spine/core/event.proto";
+import "spine/core/command.proto";
+import "spine/server/delivery/delivery.proto";
+
+
+// An identifier of an entity inbox.
+message InboxId {
+
+    // The ID of the entity.
+    spine.client.EntityId entity_id = 1;
+
+    // The type URL of the entity state.
+    string type_url = 2;
+}
+
+// A label telling how to dispatch a message, residing in the `Inbox`.
+enum InboxLabel {
+
+    IL_UNKNOWN = 0;
+
+    // Pass a command message to an `@Assign` or `@Command`-annotated command handler.
+    HANDLE_COMMAND = 1;
+
+    // Pass an event message to a `@Subscribe`-annotated event handler.
+    UPDATE_SUBSCRIBER = 3;
+
+    // Pass an event message to a `@React` or `@Command`-annotated event handler.
+    REACT_UPON_EVENT = 4;
+
+    // Retained for wire compatibility; no longer produced by the runtime.
+    //
+    // This label used to route an event to an event-importing receptor (an
+    // `@Apply` applier with `allowImport` enabled). Event import and `@Apply`
+    // were removed during the event-sourcing cutover, so nothing emits this
+    // label anymore. The value is kept so that `InboxMessage` records written
+    // by earlier versions still parse.
+    IMPORT_EVENT = 5 [deprecated = true];
+
+    // Pass an event message to the projection in scope of a catch-up process.
+    CATCH_UP = 6;
+}
+
+// A status of the message in the `Inbox`.
+enum InboxMessageStatus {
+
+    IMS_UNKNOWN = 0;
+
+    // The message is ready to be delivered.
+    TO_DELIVER = 1;
+
+    // The message is scheduled for the delivery.
+    SCHEDULED = 2;
+
+    // The message is already delivered and can be removed once it's no longer needed
+    // for deduplication.
+    DELIVERED = 3;
+
+    // The message is sent as a part of a catch-up process.
+    TO_CATCH_UP = 4;
+}
+
+// Identifies the message in the `Inbox`.
+message InboxMessageId {
+
+    // UUID-based identifier.
+    string uuid = 1 [(required) = true];
+
+    // A shard in which the identified message resides.
+    ShardIndex index = 2 [(required) = true];
+}
+
+// Identifies the original signal message that is packed inside the `InboxMessage`.
+message InboxSignalId {
+
+    // The value of the identifier of the source signal message that has been put into the `Inbox`.
+    //
+    // E.g. if an instance of `Event` is put into the `Inbox`,
+    // this field has a value of `Event.id.value`.
+    //
+    string value = 1 [(required) = true];
+}
+
+
+// A message in the inbox.
+message InboxMessage {
+
+    option (is).java_type = "io.spine.server.delivery.InboxMessageMixin";
+
+    InboxMessageId id = 1 [(required) = true];
+
+    InboxSignalId signal_id = 2 [(required) = true];
+
+    // The identifier of the `Inbox` in which this message is stored.
+    InboxId inbox_id = 3 [(required) = true];
+
+    // The `shard_index` is now a part of `InboxMessageId`.
+    reserved 4;
+    reserved "shard_index";
+
+    // What the message is.
+    oneof payload {
+
+        core.Event event = 5;
+
+        core.Command command = 6;
+    }
+
+    InboxLabel label = 7 [(required) = true];
+
+    InboxMessageStatus status = 8 [(required) = true];
+
+    // A point in time when the message was received by the `Inbox` instance.
+    google.protobuf.Timestamp when_received = 9 [(required) = true];
+
+    // An `Inbox`-internal version of the message.
+    //
+    // Used to order the messages received at the very same millisecond.
+    //
+    int32 version = 10 [(min).value = "0"];
+
+    // If set, this value determines for how long the message should be kept in the `Inbox`
+    // after being delivered. During this time it may be used for deduplication.
+    //
+    // If not set, the message will not be kept any longer than required to deliver it.
+    //
+    google.protobuf.Timestamp keep_until = 11;
+}

package/proto/spine/server/entity/entity.proto

@@ -0,0 +1,105 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+syntax = "proto3";
+
+package spine.server.entity;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option (SPI_all) = true;
+option java_package = "io.spine.server.entity";
+option java_multiple_files = true;
+option java_outer_classname = "EntityProto";
+
+import "google/protobuf/any.proto";
+
+import "spine/core/version.proto";
+
+// The record for passing information about an entity.
+message EntityRecord {
+    option (SPI_type) = true;
+    option (is).java_type = "WithLifecycle";
+
+    // The ID of the entity.
+    google.protobuf.Any entity_id = 1;
+
+    // The state of the entity.
+    google.protobuf.Any state = 2;
+
+    // The version of the entity.
+    core.Version version = 3;
+
+    // The lifecycle flags of the entity.
+    LifecycleFlags lifecycle_flags = 4;
+}
+
+// The lifecycle flags of an entity.
+message LifecycleFlags {
+
+    // Marks the entity as `archived`.
+    //
+    // An application may use this flag for filtering out entities
+    // that finished their normal lifecycle and are kept in the database
+    // for archival purposes.
+    //
+    bool archived = 1;
+
+    // Marks the entity as `deleted`.
+    //
+    // An application may use this flag for filtering out entities that were
+    // put aside (e.g. into a Trash) because they are no longer needed.
+    //
+    // An application may also use this flag for periodical automatic removal of entities
+    // marked with this flag.
+    //
+    bool deleted = 2;
+}
+
+// The change in the state of an entity.
+message EntityRecordChange {
+
+    // The value of fields that are changing.
+    EntityRecord previous_value = 1;
+
+    // The new value of fields.
+    EntityRecord new_value = 2;
+}
+
+// Enumeration of possible entity state validation errors.
+//
+// Contains the reasons for errors that are exclusively technical
+// and have no relation to business errors.
+//
+enum EntityStateValidationError {
+
+    // Reserved value.
+    UNKNOWN_REASON = 0;
+
+    // The entity state does not pass the validation.
+    INVALID_ENTITY_STATE = 1;
+}

package/proto/spine/server/entity/state_key.proto

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+syntax = "proto3";
+
+package spine.server.entity;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option (SPI_all) = true;
+option java_package = "io.spine.server.entity";
+option java_outer_classname = "StateKeyProto";
+option java_multiple_files = true;
+
+import "google/protobuf/any.proto";
+
+// Identifies a stored state of an entity: the entity and the version
+// at which the state became current.
+//
+// Serves as the record key of the entity state history, so writing the state
+// of the same entity at the same version again overwrites one record instead
+// of creating a duplicate.
+//
+message EntityStateKey {
+
+    // The packed identifier of the entity.
+    google.protobuf.Any entity_id = 1;
+
+    // The number of the entity version this state belongs to.
+    int32 version = 2;
+}