// Copyright 2024 Aalyria Technologies, Inc., and its affiliates.
//
// 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
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package aalyria.spacetime.scheduling.v1alpha;

import "api/common/field_mask.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";
import "google/rpc/status.proto";
import "google/type/interval.proto";
import "nmts/v1/proto/types/geophys/coordinates.proto";
import "nmts/v1/proto/types/geophys/geodesy.proto";


option go_package = "aalyria.com/spacetime/api/scheduling/v1alpha";
option java_package = "com.aalyria.spacetime.scheduling.v1alpha";

service Scheduling {
  // Establishes a bidirectional stream through which the SDN controller may
  // send scheduling requests to the SDN agent, and the agent may respond.
  //
  // The use of the stream allows the SDN controller to send requests to the
  // agent even though the SDN controller may not be able to initiate a
  // connection to the agent (if the agent is behind a firewall, for example,
  // or a NAT gateway).
  //
  // The SDN controller will leave the stream open indefinitely. In the event
  // that the stream closes, the agent should re-establish the stream to
  // continue receiving requests.
  rpc ReceiveRequests(stream ReceiveRequestsMessageToController)
      returns (stream ReceiveRequestsMessageFromController) {}


  // Notifies the SDN controller that an agent's schedule has been reset. The
  // agent must call this upon startup and after any event that has reset the
  // schedule.
  rpc Reset(ResetRequest) returns (google.protobuf.Empty) {}
}

// The message type for Scheduling.ReceiveRequests in the direction toward the
// controller.
message ReceiveRequestsMessageToController {
  message Hello {
    // Required. Identifies the SDN agent whose schedule is to be managed by
    // this scheduling session.
    string agent_id = 1;
  }

  message Response {
    // Required. The ID of the request to which this response corresponds. See
    // ReceiveRequestsMessageFromController.request_id.
    int64 request_id = 1;

    // The response status.
    google.rpc.Status status = 2;
  }

  // Required in the initial request of the session. Identifies the SDN agent
  // and the properties of the underlying channel.
  Hello hello = 1;

  // A response to a request received from the SDN controller.
  //
  // The response may originate from a proxy rather than the SDN agent itself.
  // For example, if the proxy is unable to deliver the request to the SDN
  // agent, the proxy may populate the response with an appropriate error.
  Response response = 2;
}

// The message type for Scheduling.ReceiveRequests in the direction from the
// controller.
//
// This is a response message in that it flows from server to client, however
// it holds requests being sent to the SDN agent (the client) by the SDN
// controller (the server).
message ReceiveRequestsMessageFromController {
  // An SDN-controller-generated value uniquely identifying the request within
  // the scope of the scheduling session. That is, two requests received from
  // the same session will always have different request IDs. The SDN agent
  // must provide the ID in the response to this request (see
  // ReceiveRequestsMessageToController.Response.request_id).
  int64 request_id = 1;

  // The contents of the request.
  oneof request {
    // Creates an entry in the agent's schedule. Note that entries are
    // immutable: once created, an entry may not changed, though it may be
    // deleted.
    //
    // The agent (or a proxy acting on its behalf) must use the CreateEntry
    // request’s response status solely to indicate transport-level receipt of
    // the request, and not to indicate whether the agent can, or will, achieve
    // the requested configuration. An error status will cause Spacetime to
    // resend the request message to the agent. 
    CreateEntryRequest create_entry = 2;

    // Deletes an entry from the agent's schedule.
    //
    // The agent (or a proxy acting on its behalf) must use the DeleteEntry
    // request’s response status to indicate transport-level receipt of the
    // request. An error status will cause Spacetime to resend the request
    // message to the agent.
    DeleteEntryRequest delete_entry = 3;

    // Finalizes all schedule entries earlier than a specified time.
    //
    // Notifies the agent that all aspects of its schedule pertaining to the
    // interval prior to a given instant will no longer be modified. This frees
    // the agent to garbage-collect all entries scheduled for before that
    // instant.
    //
    // The agent (or a proxy acting on its behalf) must use the Finalize
    // request’s response status to indicate transport-level receipt of the
    // request. An error status will cause Spacetime to resend the request
    // message to the agent.
    FinalizeRequest finalize = 4;
  }
}

message CreateEntryRequest {
  // Required. A token that must match the agent's token for the request to be
  // accepted (see ResetRequest.schedule_manipulation_token). This ensures that
  // the agent does not execute an operation intended for an old edition of the
  // schedule on a newer version.
  string schedule_manipulation_token = 1;

  // Required. The request's sequence number among all requests in the
  // Scheduling service with the same schedule manipulation token. The sequence
  // number resets with each new schedule manipulation token.
  uint64 seqno = 2;

  // Required. A unique identifier of the schedule entry being created.
  string id = 3;

  // Required. The time at which the entry is scheduled to be executed.
  google.protobuf.Timestamp time = 4;
  // `time` above as a Duration from the GPS Epoch (GPST time scale; see
  // https://gssc.esa.int/navipedia/index.php/Time_References_in_GNSS).
  google.protobuf.Duration time_gpst = 16;

  oneof configuration_change {
    UpdateBeam update_beam = 15;
    DeleteBeam delete_beam = 12;
    SetRoute set_route = 5;
    DeleteRoute delete_route = 6;
    UpdateP2pSrTePolicyPath update_p2p_sr_te_policy_path = 20;
    DeleteP2pSrTePolicyPath delete_p2p_sr_te_policy_path = 21;
    UpdateIpRoute update_ip_route = 24;
    DeleteIpRoute delete_ip_route = 25;
  }

  reserved 7, 8, 11, 13, 14, 17;
}

message SetRoute {
  // The source prefix of the route.
  //
  // An IPv4 or IPv6 address optionally followed by a slash and the prefix
  // length.
  string from = 1;

  // The destination prefix of the route.
  //
  // An IPv4 or IPv6 address optionally followed by a slash and the prefix
  // length.
  string to = 2;

  // The output device name.
  string dev = 3;

  // The address of the nexthop router.
  //
  // An IPv4 or IPv6 address.
  string via = 4;
}

message DeleteRoute {
  // The source prefix of the route.
  //
  // An IPv4 or IPv6 address optionally followed by a slash and the prefix
  // length.
  string from = 1;

  // The destination prefix of the route.
  //
  // An IPv4 or IPv6 address optionally followed by a slash and the prefix
  // length.
  string to = 2;
}

// An IP forwarding entry to be installed in an EK_ROUTE_FN's forwarding table.
//
// The time associated with a revision of an IpRoute resource in a schedule
// dictates the earliest time at which the agent should install the route into
// the indicated EK_ROUTE_FN. A route persists until superseded by a later
// IpRoute revision with the same name or removed by a DeleteIpRoute entry.
message IpRoute {
  // The resource name of the IpRoute.
  // Format: ipRoutes/{ip_route_id}
  //
  // Names are unique within a schedule. Two IpRoutes in the same schedule will
  // never share a name even if the IpRoutes exist at different times.
  string name = 1;

  // Identifies which EK_ROUTE_FN entity controlled by the receiving
  // EK_SDN_AGENT this route is installed on. Required: producers MUST
  // populate this field; agents MUST reject an IpRoute that omits it.
  string route_fn_id = 2;

  // The source prefix of the route.
  //
  // An IPv4 or IPv6 address optionally followed by a slash and the prefix
  // length.
  string from = 3;

  // The destination prefix of the route.
  //
  // An IPv4 or IPv6 address optionally followed by a slash and the prefix
  // length.
  string to = 4;

  // The output device name.
  string dev = 5;

  // The address of the nexthop router.
  //
  // An IPv4 or IPv6 address.
  string via = 6;
}

message UpdateIpRoute {
  IpRoute ip_route = 1;

  aalyria.spacetime.api.common.FieldMask update_mask = 2;
}

message DeleteIpRoute {
  // The resource name of the IpRoute to delete.
  // Format: ipRoutes/{ip_route_id}
  string name = 1;
}

// A transmit and/or receive beam of RF energy operating on a set of channels,
// whether formed by a single antenna or a beamforming array.
//
// The time associated with a revision of a Beam resource in a schedule dictates
// the earliest time at which the beam may be utilized for transmission and
// receiving on its configured channels. It is expected that the beam has been
// oriented toward its target by that time.
message Beam {
  reserved 7;

  // The ID of the beam. This ID is unique within a schedule. Two beams in the
  // same schedule will never share an ID even if the beams exist at different
  // times.
  string id = 1;

  // Identifies the pointing target for the beam to be aimed at & track.
  BeamTarget target = 2;

  // Identifies the location of the origin of the beam (local platform).
  // Note:  origin is currently supported in the API only and is not
  // yet implemented.
  BeamOrigin origin = 10;

  // Identifies the antenna that is used to transmit and/or receive the beam.
  string antenna_id = 9;

  // Parameters specifying the configuration of the beam in the receive
  // direction, keyed by arbitrary IDs.
  //
  // The string keys uniquely identify a corresponding RxConfiguration,
  // and are present only for reference in FieldMask (update) operations.
  //
  // Empty if the beam is to be used for transmit only.
  map<string, RxConfiguration> rxs = 3;

  // Parameters specifying the configuration of the beam in the transmit
  // direction, keyed by arbitrary IDs.
  //
  // The string keys uniquely identify a corresponding TxConfiguration,
  // and are present only for reference in FieldMask (update) operations.
  //
  // Empty if the beam is to be used for receiving only.
  map<string, TxConfiguration> txs = 4;

  // The collection of endpoints served by the beam.
  // For example, a collection of user terminals (UTs) served.
  //
  // Each key is the ID of the endpoint's network node in Spacetime's network
  // model.
  map<string, Endpoint> endpoints = 5;

  // ID of the beam shape.
  string shape_id = 6;

  // Only present if beam-hopping is to be used.
  BeamHoppingPlan beam_hopping_plan = 8;

  // The IDs of all beams that are transmitting to the endpoints served by this
  // beam.
  //
  // Note that, for any transmit beam, tx_beams will contain that beam's own ID.
  repeated string tx_beams = 11;
}

message BeamHoppingPlan {
  message Section {
    // The length of the section, in number of time slots.
    int32 length = 1;

    // An entry in the beam-hopping plan section representing a time slot during
    // which the associated beam is to be illuminated.
    message Entry {
      // The entry's time slot within the section.
      int32 time_slot = 1;

      string modem_id = 2;
    }

    // The entries in the beam-hopping plan section. The beam should not be
    // illuminated during any time slot not represented in the collection of
    // entries.
    repeated Entry entries = 2;

    // The number of extra times that the list of time slots defined by the
    // section should be looped.  A zero value (no repeats) is assumed if not
    // present, which means the entries are only visited once by the beam.  A
    // value of 2 means the section is iterated through and then repeated
    // twice (so all of the entries are visited three times by the beam).
    // Negative values should not be used; the type is signed in accordance
    int32 repeat_count = 3;
  }

  repeated Section sections = 1;
}

message UpdateBeam {
  Beam beam = 1;

  aalyria.spacetime.api.common.FieldMask update_mask = 2;
}

message DeleteBeam {
  string id = 1;
}


// BeamTarget type will be populated according to the Antenna.pointing_format
// field specified in the relevant Model entities.
//
// This message will not be populated when the antenna's pointing format is 
// unset.
message BeamTarget {
  oneof target {
    Cartesian cartesian = 4;
    string ccsds_oem_file_content = 2;
    AzEl az_el = 3;
    StateVector state_vector = 5;
    ChebyshevCoefficients chebyshev_coefficients = 6;
  }

  reserved 1;
}

// This is the expected location of the beam origin based on the projected
// motion.  This may diverge from the actual position of the spacecraft
// and is not intended to be guidance or to influence the vehicle motion
// in any way.  This can be used to compute beam pointing vectors (origin
// to target) in agents that are not aware of the local platform position
// via other means.
//
// BeamOrigin type will be populated according to the Antenna.origin_format
// field specified in the relevant Model entities.
message BeamOrigin {
  oneof origin {
    Cartesian cartesian = 1;
    string ccsds_oem_file_content = 2;
    StateVector state_vector = 3;
    ChebyshevCoefficients chebyshev_coefficients = 4;
  }
}

// Coefficients for a Chebyshev Polynomial.
message ChebyshevCoefficients {
  nmts.v1.types.geophys.CoordinateFrame reference_frame = 1;

  // Lists of coefficients.
  // Note: length of list implies the degree of the polynomial
  // (e.g. len(coefficient) = Degree of Polynomial + 1)
  //
  // In each list, the value at idx i is the coefficient of the
  // Chebyshev Polynomial of order i.
  //
  // Note:  this uses the convention where the first coefficient is
  // multiplied by 1/2 (i.e. p(x) = c_0 / 2.0 + \sum_{n=1}{c_n*T_n(x)}).
  // See:  https://www.gnu.org/software/gsl/doc/html/cheb.html
  //
  // The evaluation domain is [-1, 1]. To evaluate at a time t within the
  // validity period [t_start, t_end], normalize as:
  //   x = 2 * (t - t_start) / (t_end - t_start) - 1
  //
  // Coefficients for X,Y,Z Position (in meters).
  repeated double x_m_coefficients = 2;
  repeated double y_m_coefficients = 3;
  repeated double z_m_coefficients = 4;

  // Coefficents for X_dot, Y_dot, Z_dot Velocity (in meters per second)
  repeated double x_dot_m_per_s_coefficients = 5;
  repeated double y_dot_m_per_s_coefficients = 6;
  repeated double z_dot_m_per_s_coefficients = 7;

  // The period of time over which these coefficients are valid. The
  // start and end times can be defined in UTC and/or GPS timestamps.
  // `_gpst` below as a Duration from the GPS Epoch (GPST time scale; see
  // https://gssc.esa.int/navipedia/index.php/Time_References_in_GNSS).
  google.protobuf.Timestamp validity_period_start_time = 8;
  google.protobuf.Duration validity_period_start_time_gpst = 9;
  google.protobuf.Timestamp validity_period_end_time = 10;
  google.protobuf.Duration validity_period_end_time_gpst = 11;
}

message Cartesian {
  nmts.v1.types.geophys.CoordinateFrame reference_frame = 1;

  double x_m = 2;
  double y_m = 3;
  double z_m = 4;
}

message StateVector {
  nmts.v1.types.geophys.CoordinateFrame reference_frame = 1;

  double x_m = 2;
  double y_m = 3;
  double z_m = 4;
  double x_dot_m_per_s = 5;
  double y_dot_m_per_s = 6;
  double z_dot_m_per_s = 7;
}

// An azimuth and elevation angle pair.
//
// The azimuth angle of a vector is the angle between the x-axis and the
// orthogonal projection of the vector onto the xy plane. The angle is positive
// in going from the x axis toward the y axis. The elevation angle is the angle
// between the vector and its orthogonal projection onto the xy-plane.
message AzEl {
  // Azimuth, in degrees.
  double az_deg = 1;

  // Elevation, in degrees.
  double el_deg = 2;
}

message RxConfiguration {
  uint64 center_frequency_hz = 1;
  uint64 channel_bandwidth_hz = 2;
  Polarization polarization = 3;
  // Corresponds to an nmts.v1.ek.physical.Carrier.config_id of a carrier within
  // an nmts.v1.ek.physical.CarrierConfiguration. In NMTS graphs, demodulators
  // are associated with CarrierConfigurations through receivers, e.g.,
  // Demodulator <--RK_SIGNAL_TRANSITS--
  //    SignalProcessingChain <--RK_SIGNAL_TRANSITS--
  //        Receiver <--RK_SIGNAL_TRANSITS-- Antenna
  //            |
  //            |--RK_SUPPORTS--> CarrierConfiguration
  string carrier_config_id = 9;

  // Expected received power under nominal closed-loop power control.
  // Steady-state operating point the system is intended to maintain,
  // derived from configured constraints (e.g., PFD limits).
  RxPower expected_rx_power = 8;

  // Expected received power at signal acquisition, used to initialize receiver
  // AGC before closed-loop power control converges. Computed from the link
  // budget when the link is established and held constant while the link is
  // active.
  RxPower initial_rx_power = 13;

  // Symbol rate in Megasymbols per second.
  double symbol_rate_msps = 5;

  // The roll-off factor, which is a measure of the excess bandwidth of a
  // carrier’s pulse-shaping filter, as a decimal value. This value is not
  // computed; rather, it is populated from the assigned carrier's
  // nmts.v1.ek.physical.Carrier.roll_off_factor.
  // Note: The channel bandwidth, symbol rate, and roll-off parameters hold
  // redundant information (since with any two of those parameters the third
  // value is computable), but all three can be provided to a client for clarity
  // and convenience.
  float roll_off_factor = 10;

  // Identifies the demodulator associated with the carrier on this beam.
  // Must be present if beam-hopping is not used, otherwise it should be
  // empty and the demodulator IDs are found via the beam hopping plan.
  string demodulator_id = 6;

  // Identifies the port associated with the carrier on this beam. This
  // corresponds to the NMTS entity ID of an nmts.v1.ek.physical.Port. In NMTS
  // graphs, ports are related to demodulators through an RK_TERMINATES
  // relationship, e.g., Port --RK_TERMINATES--> Demodulator.
  string port_id = 12;

  // This value corresponds to the nmts.v1.ek.physical.Carrier.waveform of the
  // carrier assigned to this beam. nmts.v1.ek.physical.Carriers are defined in
  // nmts.v1.ek.physical.CarrierConfigurations.
  string waveform = 4;

  string initial_modcod = 11;

  // Includes technology-specific parameters needed for particular link and
  // physical layer technology standards, such as DVB-S2X, etc.
  oneof other_parameters {
    DvbS2Params dvbs2_params = 7;
  }

  // The GSE label the receiving modem uses to filter this element's own stream
  // from the multiplexed DVB-S2 carrier. This label is set based on the GSE
  // label in a nmts.v1.ek.logical.LogicalPacketLink that the transmitting
  // endpoint originates, if one exists. The transmitting endpoint would be
  // modeled as:
  // Interface --RK_ORIGINATES--> LogicalPacketLink (with GsePayload)
  int32 gse_label = 14;

  reserved 15 to max;
}

message TxConfiguration {
  uint64 center_frequency_hz = 1;
  uint64 channel_bandwidth_hz = 2;
  Polarization polarization = 3;
  // Corresponds to an nmts.v1.ek.physical.Carrier.config_id of a carrier within
  // an nmts.v1.ek.physical.CarrierConfiguration. In NMTS graphs, modulators are
  // associated with CarrierConfigurations through transmitters, e.g.,
  // Modulator --RK_SIGNAL_TRANSITS-->
  //    SignalProcessingChain --RK_SIGNAL_TRANSITS-->
  //        Transmitter --RK_SIGNAL_TRANSITS--> Antenna
  //            |
  //            |--RK_SUPPORTS--> CarrierConfiguration
  string carrier_config_id = 10;

  // The initial transmit power for the beam.
  TxPower initial_tx_power = 13;

  // The transmit power the transmitter must not exceed to avoid violating
  // interference or received power constraints.
  TxPower max_tx_power = 14;

  // Symbol rate in Megasymbols per second.
  double symbol_rate_msps = 6;
  // The roll-off factor, which is a measure of the excess bandwidth of a
  // carrier’s pulse-shaping filter, as a decimal value. This value is not
  // computed; rather, it is populated from the assigned carrier's
  // nmts.v1.ek.physical.Carrier.roll_off_factor.
  // Note: The channel bandwidth, symbol rate, and roll-off parameters hold
  // redundant information (since with any two of those parameters the third
  // value is computable), but all three can be provided to a client for clarity
  // and convenience.
  float roll_off_factor = 11;

  // Identifies the modulator associated with the carrier on this beam.
  // Must be present if beam-hopping is not used, otherwise it should be
  // empty and the modulator IDs are found via the beam hopping plan.
  string modulator_id = 8;

  // Identifies the port associated with the carrier on this beam. This
  // corresponds to the NMTS entity ID of an nmts.v1.ek.physical.Port. In NMTS
  // graphs, ports are related to modulators through an RK_ORIGINATES
  // relationship, e.g., Port --RK_ORIGINATES--> Modulator.
  string port_id = 12;

  // This value corresponds to the nmts.v1.ek.physical.Carrier.waveform of the
  // carrier assigned to this beam. nmts.v1.ek.physical.Carriers are defined in
  // aalyria.spacetime.api.common.nmts.v1.ek.physical.CarrierConfigurations.
  string waveform = 4;

  string initial_modcod = 7;

  // Includes technology-specific parameters needed for particular link and
  // physical layer technology standards, such as DVB-S2X, etc.
  oneof other_parameters {
    DvbS2Params dvbs2_params = 9;
  }

  reserved 15 to max;
}

enum Polarization {
  POLARIZATION_UNSPECIFIED = 0;
  POLARIZATION_LHCP = 1; // Left-handed circular polarization
  POLARIZATION_RHCP = 2; // Right-handed circular polarization
}

message RxPower {
  oneof value {
    // Power Flux Density at receiver [dBW/m^2].
    double pfd_dbw_per_m2 = 1;
  }
}

message TxPower {
  oneof value {
    // Beam Peak Effective Isotropic Radiated Power Spectral Density [dBW/MHz].
    double beam_peak_eirpsd_dbw_per_mhz = 1;
  }
}

// Groups configurable attributes specific to DVB-S2 / S2X links.
message DvbS2Params {
  // Identifies the physical layer scrambling codes used for payload data and
  // pilot symbols.  Mapping to particular sequences may be user-defined.
  uint32 payload_pl_scrambling_code = 1;
  uint32 pilot_pl_scrambling_code = 2; 
}

message Endpoint {
  string lowest_supported_rx_modcod = 2;
  double rx_reference_throughput_bps = 3;
  double tx_reference_throughput_bps = 4;

  // Indicates the CIR and EIR used in plan generation, as guidance for
  // realtime demand-based management systems.
  double commited_information_rate_bps = 5;
  double excess_information_rate_bps = 6;

  EndpointSecurity security = 7;

  // This field maps incoming MPLS labels at the transmitting node to the
  // corresponding port through which traffic for this endpoint is transmitted.
  //
  // Each key is the topmost MPLS label on packets arriving at the transmitting
  // node that identifies traffic to be forwarded to this endpoint. Each value
  // is the NMTS entity ID of the nmts.v1.ek.physical.Port on the transmitting
  // node through which traffic for that label is transmitted.
  //
  // For example, for a Beam that represents a satellite's user downlink beam,
  // this endpoint could represent a user terminal. In that case, a key in this
  // map indicates the MPLS label used in the satellite's dataplane to forward
  // packets to the user terminal. The corresponding value is the port on the
  // satellite used to transmit that traffic.
  //
  // Consider an interface on the transmitting node modeled in an NMTS graph as:
  //   Interface --RK_ORIGINATES--> LogicalPacketLink
  //       |
  //       |--RK_TRAVERSES--> Port --RK_ORIGINATES--> Modulator ...
  //
  // Each key is populated with the sr.adjacency_sid.mpls value from the
  // nmts.v1.ek.logical.LogicalPacketLink, and the corresponding value is the
  // entity ID of the port that the interface traverses.
  //
  // Assigning multiple carriers on one beam to transmit to this endpoint
  // involves tasking multiple ports, each of which is associated with one
  // SR-MPLS Adjacency SID. In these cases, there will be one entry per carrier
  // in this map.
  //
  // Note that this field is only populated for endpoints of transmit beams.
  map<int32, string> incoming_mpls_label_to_egress_port = 11;

  reserved 1, 8, 9, 10;
}

message EndpointSecurity {
  // Identifies or provides key information for reception from and transmission
  // to the endpoint.
  string rx_key = 1;
  string tx_key = 2;
}

message P2pSrTePolicyPath {
  // The resource name of the path.
  // Format: p2pSrTePolicyPaths/{path_id}
  string name = 1;

  // Immutable.
  int32 color = 2;

  // RFC 9256 S2.5 Discriminator. Immutable.
  int32 discriminator = 3;

  // entity.id of the source EK_ROUTE_FN. Immutable.
  string headend = 4;

  // entity.id of the destination EK_ROUTE_FN. Immutable.
  string endpoint = 5;

  // An ordered list of segments from ingress to egress.
  //
  // An empty list indicates that the P2pSrTePolicyCandidatePath provisioning
  // request associated with this <Headend, Color, Endpoint, Descriminator>
  // tuple could not be fulfilled.
  repeated SrSegment segments = 6;
}

message UpdateP2pSrTePolicyPath {
  // The path to update.
  P2pSrTePolicyPath p2p_sr_te_policy_path = 1;

  aalyria.spacetime.api.common.FieldMask update_mask = 2;
}

message DeleteP2pSrTePolicyPath {
  // The name of the path to delete.
  string name = 1;
}

// Identifiers for an SR segment (a SID).
//
// It is an error if multiple dataplane SIDs are present in this message
// and do not all identify the same logical segment.
message SrSegment {
  // An RFC 8294 mpls-label
  //
  // Typically an RFC 9256 SR-DB Type A segment, but may be any
  // segment with an MPLS dataplane identifier (label).
  //
  // The proto3-default value of zero (0) here is only valid iff:
  //   - this is the last SR segment in a sequence, AND
  //   - the SRv6 SID field is empty OR it contains an SRv6 SID that
  //     identifies behavior equivalent to the RFC 3032 IPv4 Explicit
  //     NULL Label behavior (e.g. RFC 8986 Section 4.16 variant SIDs).
  uint32 mpls = 1;

  // An RFC 6991 ipv6-address-no-zone
  //
  // Typically an RFC 9256 SR-DB Type B segment, but may be any
  // segment with an SRv6 dataplane identifier (IPv6 address).
  //
  // For more on the relationship between SRv6 SIDs and the IPv6
  // addressing architecture see RFC 9602.
  string srv6 = 2;
}

// NR Cell Global Identity, shared by UpdateHandoverTrigger and
// DeleteHandoverTrigger.
message NewRadioCellGlobalId {
  // Mobile Country Code (MCC) - 3 digits
  uint32 mcc = 1;

  // Mobile Network Code (MNC) - 2 or 3 digits
  uint32 mnc = 2;

  // gNodeB ID
  // equivalent to 22-32 binary bits (w/ cell_local_id totals 36 bits)
  uint32 gnb_id = 3;

  // gNodeB ID Length in bits
  // 22-32
  uint32 gnb_id_length = 4;

  // Cell Local ID - 4-14 bits (w/ gnb_id totals 36 bits)
  // equivalent to 4-14 binary bits (w/ gnb_id totals 36 bits)
  uint32 cell_local_id = 5;
}

message UpdateHandoverTrigger {
  // Mobility signaling for networks adopting one of the Digital Video
  // Broadcasting (DVB) family of access networks, e.g. DVB-S, DVB-S2,
  // DVB-S2X, etc. There are no exact standards which define what mobility
  // procedures in DVB based networks requires as input information, so it is
  // for now being defined to include a source and target EK_NETWORK_NODE ID.
  message Dvb {
    string source_network_node_id = 1;
    string target_network_node_id = 2;
  }

  // Mobility signaling for networks adopting the 5G New Radio (NR) Radio
  // Access Technology (RAT).
  message Nr {
    // Legacy, network-initiated L3 Handover
    message L3HO {
    }

    // Time-based Conditional Handover (CHO).
    // See condEventT1-r17 in TS 38.331 Release 18.
    // Ref: https://www.etsi.org/deliver/etsi_ts/138300_138399/138331/18.02.00_60/ts_138331v180200p.pdf
    message T1CHO {
      // "The field counts the number of UTC seconds in 10 ms units since
      // 00:00:00 on Gregorian calendar date 1 January, 1900 (midnight between
      // Sunday, December 31, 1899 and Monday, January 1, 1900)."
      //
      // As per above definition from 3GPP TS 38.331, the value is to be
      // quantised into units of 10ms when being provided to the NTN RAN.
      google.protobuf.Timestamp t1_threshold = 1;

      // "This field is used for defining the leaving condition T1-2 for
      // conditional HO event condEventT1.
      // Each step represents 100ms"
      //
      // As per above definition from 3GPP TS 38.331, the value is to be
      // quanitsed into units of 100ms when being provided to the NTN RAN.
      google.protobuf.Duration duration = 2;

      // Conditional reconfiguration identifier. Scoped per source NR CGI
      // cell, must not overlap with D1CHO cond_reconfig_id_r16s.
      // Maximum value 64.
      int32 cond_reconfig_id_r16 = 3;
    }

    // Distance-based Conditional Handover (CHO).
    // See condEventD1-r17 in TS 38.331 Release 18
    // Ref: https://www.etsi.org/deliver/etsi_ts/138300_138399/138331/18.02.00_60/ts_138331v180200p.pdf
    message D1CHO {
      // As per 3GPP TS 38.331
      // Distance from a fixed reference location configured with
      // referenceLocation1 or referenceLocation2 or a moving reference location
      // determined by the UE based on the serving cell movingReferenceLocation
      // broadcast in SIB19 or referenceLocation2 and their corresponding
      // satellite ephemeris and epoch time. Each step represents 50m.
      int32 distance_thresh_from_reference_1_50m = 1;
      int32 distance_thresh_from_reference_2_50m = 2;

      // Defined in TS 38.331 as a ReferenceLocation-r17 IE, of type OCTET
      // STRING. The OCTET STRING represents an ASN.1 APER encoded
      // representation of the Ellipsoid-Point from TS 37.355, which itself
      // has the following structure
      // -- ASN1START
      // Ellipsoid-Point ::= SEQUENCE {
      //  latitudeSign ENUMERATED {north, south},
      //  degreesLatitude INTEGER (0..8388607), -- 23 bit field
      //  degreesLongitude INTEGER (-8388608..8388607) -- 24 bit field
      // }
      // -- ASN1STOP
      nmts.v1.types.geophys.GeodeticWgs84 reference_location_1 = 3;
      nmts.v1.types.geophys.GeodeticWgs84 reference_location_2 = 4;

      // As per 3GPP TS 38.331
      // "The IE HysteresisLocation is a parameter used within entry and leave
      // condition of a location based event triggered reporting condition.
      // The actual value is field value * 10 meters."
      int32 hysteresis_location_10m = 6;

      // As per 3GPP TS 38.331
      // "The IE TimeToTrigger specifies the value range used for time to
      // trigger parameter, which concerns the time during which specific
      // criteria for the event needs to be met in order to trigger a
      // measurement report. Value ms0 corresponds to 0 ms and behaviour as
      // specified in 7.1.2 applies, value ms40 corresponds to 40 ms, and so
      // on."
      //
      // The possible valid values are the following:
      // ms0, ms40, ms64, ms80, ms100, ms128, ms160, ms256, ms320, ms480, ms512,
      // ms640, ms1024, ms1280, ms2560, ms5120
      google.protobuf.Duration time_to_trigger = 5;

      // Conditional reconfiguration identifier. Scoped per source NR CGI
      // cell, maximum value 64. When the cell occupying a neighbour area
      // changes, the D1CHO config with the same cond_reconfig_id_r16 is updated
      // via a new UpdateHandoverTrigger rather than deleted and recreated.
      int32 cond_reconfig_id_r16 = 7;
    }

    // Satellite Switch with Resynchronization.
    // See SatSwitchWithReSync-r17 in TS 38.331 Release 18
    // Ref: https://www.etsi.org/deliver/etsi_ts/138300_138399/138331/18.02.00_60/ts_138331v180200p.pdf
    message SatSwitchWithReSync {
      // "Indicates the time information on when the target satellite is going
      // to start serving the area currently covered by the serving satellite.
      // The field indicates a time in multiples of 10ms after 00:00:00 on
      // Gregorian calendar date 1st January 1900 (midnight between Sunday,
      // December 31, 1899, and Monday, January 1, 1900). The exact start time
      // is between the time indicated by the value of this field minus 1 and
      // the time indicated by the value of this field. The reference point for
      // t-ServiceStart is the uplink time synchronization reference point of
      // the serving satellite.
      //
      // As per above definition from 3GPP TS 38.331, the value is to be
      // quantised into units of 10ms when being provided to the NTN RAN.
      //
      // Alternatively delivered within ThreeGPPCell.ntn_sib19_validity_interval
      google.protobuf.Timestamp t_service_start = 1;

      // "Indicates the time offset between the SSB from source and target
      // satellite at the uplink time synchronization reference point. It is
      // given in number of subframes."
      int32 ssb_time_offset_count = 2;
    }

    // Source and Target NR Cell Global IDs.
    NewRadioCellGlobalId source_nr_cgi = 1;
    NewRadioCellGlobalId target_nr_cgi = 2;

    oneof handover_type {
      L3HO l3_ho = 3;
      T1CHO t1_cho = 4;
      D1CHO d1_cho = 5;
      SatSwitchWithReSync sat_switch_with_re_sync = 6;
    }
  }

  message EndpointList {
    repeated string endpoint_ids = 1;
  }

  // Compiler-assigned identifier for this handover trigger instance.
  // Used by schedulingsync to track identity across schedule revisions,
  // following the same pattern as Beam.id and ThreeGPPCell.Nr.id.
  string id = 1;

  oneof access_type {
    Dvb dvb = 2;
    Nr nr = 3;
  }

  // Other subjects TBD.
  oneof subject {
    BeamTarget target = 4;
    EndpointList endpoint_list = 5;
  }
}

// Removes a handover trigger from the agent's schedule, identified by id.
message DeleteHandoverTrigger {
  message Dvb {
    string source_network_node_id = 1;
  }

  message Nr {
    NewRadioCellGlobalId source_nr_cgi = 1;
    int32 cond_reconfig_id_r16 = 2;
  }

  // The id of the UpdateHandoverTrigger to remove.
  string id = 1;

  oneof access_type {
    Dvb dvb = 2;
    Nr nr = 3;
  }
}

message DeleteEntryRequest {
  // Required. A token that must match the agent's token for the request to be
  // accepted (see ResetRequest.schedule_manipulation_token). This ensures that
  // the agent does not execute an operation intended for an old edition of the
  // schedule on a newer version.
  string schedule_manipulation_token = 1;

  // Required. The request's sequence number among all requests in the
  // Scheduling service with the same schedule manipulation token. The sequence
  // number resets with each new schedule manipulation token.
  uint64 seqno = 2;

  // Required. The schedule entry to delete.
  string id = 3;
}

message FinalizeRequest {
  // Required. A token that must match the agent's token for the request to be
  // accepted (see ResetRequest.schedule_manipulation_token). This ensures that
  // the agent does not execute an operation intended for an old edition of the
  // schedule on a newer version.
  string schedule_manipulation_token = 1;

  // Required. The request's sequence number among all requests in the
  // Scheduling service with the same schedule manipulation token. The sequence
  // number resets with each new schedule manipulation token.
  uint64 seqno = 2;

  // Required. The time before which the schedule will no longer be modified.
  google.protobuf.Timestamp up_to = 3;
  // `up_to` above as a Duration from the GPS Epoch (GPST time scale; see
  // https://gssc.esa.int/navipedia/index.php/Time_References_in_GNSS).
  google.protobuf.Duration up_to_gpst = 4;
}

message ResetRequest {
  // Required. Identifies the agent whose schedule has been reset.
  string agent_id = 1;

  // Required. The new schedule's manipulation token. Only requests annotated
  // with a matching token should be accepted.
  string schedule_manipulation_token = 2;
}