turboci/graph/orchestrator/v1/value_write.proto

// Copyright 2026 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";

package turboci.graph.orchestrator.v1;

import "google/protobuf/any.proto";
import "turboci/graph/orchestrator/v1/tags.proto";

option go_package = "go.chromium.org/turboci/proto/go/graph/orchestrator/v1;orchestratorpb";
option java_multiple_files = true;

// ValueWrite wraps data (as a google.protobuf.Any) plus information about the
// security realm associated with that data.
//
// ValueWrite is used only in write requests; the orchestrator will ingest the
// data into a [ValueRef]/[ValueData] pair. It will use heuristics to decide
// whether to store the [ValueData] separately via `digest`, or inline with
// the [ValueRef].
message ValueWrite {
  // The actual data to write.
  optional google.protobuf.Any data = 1;

  // Maps this data to a security realm.
  //
  // If the value already exists, its realm must match the realm provided here.
  // If there is a mismatch, the write will fail with FAILED_PRECONDITION.
  //
  // Three special values are allowed here:
  //   * unset - If the `realm` field is unset on a write, then this Value MUST
  //     already exist prior to the write (otherwise the write will fail with
  //     FAILED_PRECONDITION). The existing value's realm will be used.
  //   * "$from_token" - If this value is set, then the realm of the current
  //     writer, based on the supplied `token` will be used. For Stage Attempt
  //     implementations, this will be the realm of the Stage they are running
  //     as. For WorkPlan Creation tokens, this will be the realm of the
  //     WorkPlan.
  //   * "$from_container" - If this value is set, then the realm of the
  //     container (node which contains this Value) will be used. The container
  //     node must already exist prior to this write, or this write must set
  //     its realm (e.g. you can write a check and its option in the same
  //     write).
  //       * Checks and Stages are contained in the WorkPlan.
  //       * Check Options, Check Result Data, etc. are contained in their
  //         Check.
  //       * Stage Attempt Details, Stage Attempt Progress Details, etc. are
  //         contained in their Stage.
  //       * Edit Reasons for a Check or Stage are contained in their
  //         respective Edit, which always has the same realm as the Check or
  //         Stage to which the Edit belongs.
  //   * "$legacy_worknode" - Can only be used only for Values contained by
  //     a stage that has `identifier.is_worknode` set to true. Indicates that
  //     access to the value is governed by legacy WorkPlan API ACLs, not
  //     realms. Useful for compatibility with WorkPlan executors.
  //
  // See the surrounding context for this ValueWrite for which permissions
  // will be checked for writing and/or reading this data.
  optional string realm = 2;

  // Additional tags to associate with the written data.
  //
  // Typically you should not set these directly; they should be generated for
  // you using the `turboci.tag` field annotations in your protos, using one of
  // the Turbo CI helper libraries (such as the Go or Python libraries in this
  // repo).
  repeated Tag tags = 3;
}