syntax = "proto3";

package nexuscrm.runtime.v1;

import "common/v1/common.proto";

option go_package = "github.com/pingcap-inc/nexuscrm-contract/wire-go/gen/runtime/v1;runtimev1";

service FlowExecutionService {
  rpc ExecuteFlow(ExecuteFlowRequest) returns (ExecuteFlowResponse);
  // PreviewCatalogAction evaluates one immutable Catalog-bound action through
  // a no-effect Flow profile. N-1 servers do not implement this additive RPC
  // and therefore fail closed with UNIMPLEMENTED.
  rpc PreviewCatalogAction(PreviewCatalogActionRequest) returns (PreviewCatalogActionResponse);
}

message ExecuteFlowRequest {
  // Required for an ordinary Flow request and empty when catalog_action is
  // present. Catalog-action Flow identity is derived from the immutable
  // Catalog view, never selected independently by the request.
  string definition_ref = 1;
  // Required for an ordinary Flow request and empty when catalog_action is
  // present.
  string definition_version = 2;
  string idempotency_key = 3;
  bytes canonical_inputs = 4;
  optional uint64 min_catalog_revision = 5;
  // Presence selects the Catalog-action profile. Keeping fields 1 and 2 empty
  // makes an N-1 server that ignores this additive field fail closed under the
  // ordinary Flow validator instead of executing a different Flow.
  optional CatalogActionBinding catalog_action = 6;
}

message CatalogActionBinding {
  string component_ref = 1;
  string action_ref = 2;
}

message ExecuteFlowResponse {
  string execution_id = 1;
  reserved 2;
  bytes canonical_outputs = 3;
  // Raw engine causes and internal diagnostics remain unrepresentable.
  reserved 4;
  nexuscrm.common.v1.ConsistencyReceipts receipts = 5;
  // Present only for a terminal business rejection already approved by the
  // Runtime Flow presentation gate. Infrastructure, authorization, and
  // non-presentable Engine failures remain top-level gRPC failures.
  repeated FlowExecutionError errors = 6;
}

message FlowExecutionError {
  // Opaque L1-owned product error code within the semantic token grammar.
  string code = 1;
  // Runtime-approved caller-visible text, never arbitrary error.Error() text.
  string message = 2;
  repeated string fields = 3;
}

enum CatalogActionPreviewMode {
  CATALOG_ACTION_PREVIEW_MODE_UNSPECIFIED = 0;
  CATALOG_ACTION_PREVIEW_MODE_CREATE_RECORDS = 1;
  CATALOG_ACTION_PREVIEW_MODE_OUTPUTS = 2;
}

message PreviewCatalogActionRequest {
  CatalogActionPreviewMode mode = 1;
  // Present only for CREATE_RECORDS and contains the selected action's
  // canonical input object.
  bytes canonical_inputs = 2;
  optional uint64 min_catalog_revision = 3;
  CatalogActionBinding catalog_action = 4;
  // Present only for OUTPUTS. Runtime derives the preview Flow input name from
  // the immutable action schema rather than accepting a caller-selected name.
  string record_id = 5;
}

message PreviewCatalogActionResponse {
  bytes canonical_result = 1;
  nexuscrm.common.v1.ConsistencyReceipts receipts = 2;
}