From fbd9bcb223c2fe248c7d0a21102cf9d0232c52b6 Mon Sep 17 00:00:00 2001
From: Tiago Quelhas <tjgq@google.com>
Date: Wed, 31 Jan 2024 13:27:20 +0000
Subject: [PATCH] [7.1.0] Make some minor adjustments to the compact execution
 log format and document it better. (#21146)

* Remove the Output top-level payload type. It can only appear as a
sub-message of a Spawn.
* Add an Invocation top-level payload type. It is currently empty but
reserved for anticipated needs (e.g. to report the digest function
used).
* Spell out some guarantees (and non-guarantees) about the format.

Renumbering is fine, since the format hasn't made it into a release yet.

PiperOrigin-RevId: 602352295
Change-Id: I6044c9a9a51360dfce5701071883b318b1e9a5c2
---
 src/main/protobuf/spawn.proto | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/src/main/protobuf/spawn.proto b/src/main/protobuf/spawn.proto
index 600ecf12edeca3..49469427680998 100644
--- a/src/main/protobuf/spawn.proto
+++ b/src/main/protobuf/spawn.proto
@@ -200,7 +200,18 @@ message SpawnExec {
 // Each entry describes either an executed spawn or a piece of data referenced
 // by other entries. This considerably reduces the runtime overhead and the size
 // of the log when compared to the --execution_log_{binary,json}_file formats.
+//
+// To ensure that the log can be parsed in a single pass, every entry must be
+// serialized after all other entries it references by ID.
+//
+// Entries other than spawns may not be assumed to be canonical. For performance
+// reasons, the same file, directory or input set may be serialized multiple
+// times with a different ID.
 message ExecLogEntry {
+  // Information pertaining to the entire invocation.
+  // May appear at most once in the initial position.
+  message Invocation {}
+
   // An input or output file.
   message File {
     // The file path.
@@ -220,6 +231,10 @@ message ExecLogEntry {
   }
 
   // A set of spawn inputs.
+  // The contents of the set are the directly referenced files and directories
+  // in addition to the contents of all transitively referenced sets. Sets are
+  // not canonical: two sets with different structure may yield the same
+  // contents.
   message InputSet {
     // Entry IDs of files belonging to this set.
     repeated int32 file_ids = 1;
@@ -303,10 +318,10 @@ message ExecLogEntry {
 
   // The entry payload.
   oneof type {
-    File file = 2;
-    Directory directory = 3;
-    InputSet input_set = 4;
-    Output output = 5;
+    Invocation invocation = 2;
+    File file = 3;
+    Directory directory = 4;
+    InputSet input_set = 5;
     Spawn spawn = 6;
   }
 }