pidl

type Alternative struct {
	// Condition describes when this alternative is taken.
	Condition string `json:"condition"`

	// Flows are the steps in this alternative path.
	Flows []Flow `json:"flows"`

	// Description provides additional context.
	Description string `json:"description,omitempty"`
}

type AnimationPreset string

type Annotation struct {
	// Type categorizes the annotation.
	Type AnnotationType `json:"type"`

	// Text is the annotation message.
	Text string `json:"text"`

	// Details provides additional context.
	Details string `json:"details,omitempty"`
}

type AnnotationType string

type Breakpoint struct {
	// FlowIndex is the flow index where the breakpoint is set.
	FlowIndex int

	// Condition is an optional condition expression (evaluated by ConditionEvaluator).
	Condition string

	// Enabled indicates if the breakpoint is active.
	Enabled bool

	// HitCount tracks how many times this breakpoint was hit.
	HitCount int
}

type Category string

type CostEstimate struct {
	// EntityID is the entity this estimate is for (empty for total).
	EntityID string `json:"entity_id,omitempty"`
	// MinCost is the minimum expected cost.
	MinCost float64 `json:"min_cost"`
	// MaxCost is the maximum expected cost.
	MaxCost float64 `json:"max_cost"`
	// ExpectedCost is the average/expected cost.
	ExpectedCost float64 `json:"expected_cost"`
	// CostUnit is the currency or unit.
	CostUnit string `json:"cost_unit"`
	// Breakdown shows cost by category.
	Breakdown map[string]float64 `json:"breakdown,omitempty"`
}

type CostModel struct {
	// Type classifies the cost model.
	Type CostModelType `json:"type"`

	// FixedCost is the base cost per execution (in the cost unit).
	FixedCost float64 `json:"fixed_cost,omitempty"`

	// VariableCost is the cost per unit of work.
	VariableCost float64 `json:"variable_cost,omitempty"`

	// CostUnit is the currency or unit for costs (e.g., "USD", "tokens", "credits").
	CostUnit string `json:"cost_unit,omitempty"`

	// TokenCosts for LLM steps (per 1K tokens).
	InputTokenCost  float64 `json:"input_token_cost,omitempty"`
	OutputTokenCost float64 `json:"output_token_cost,omitempty"`

	// EstimatedInputTokens for LLM cost estimation.
	EstimatedInputTokens int `json:"estimated_input_tokens,omitempty"`
	// EstimatedOutputTokens for LLM cost estimation.
	EstimatedOutputTokens int `json:"estimated_output_tokens,omitempty"`

	// ComputeCostPerSecond for compute-based steps.
	ComputeCostPerSecond float64 `json:"compute_cost_per_second,omitempty"`

	// APICallCost for external API steps.
	APICallCost float64 `json:"api_call_cost,omitempty"`
}

type CostModelType string

type DataLineage struct {
	// ProtocolID is the ID of the source protocol.
	ProtocolID string `json:"protocol_id"`
	// Edges are the data flow connections.
	Edges []LineageEdge `json:"edges"`
	// Sources are ports that have no upstream connections.
	Sources []PortReference `json:"sources"`
	// Sinks are ports that have no downstream connections.
	Sinks []PortReference `json:"sinks"`
	// SensitiveDataPaths tracks paths containing sensitive data.
	SensitiveDataPaths [][]PortReference `json:"sensitive_paths,omitempty"`
}

type DataPort struct {
	// Kind classifies the data type.
	Kind DataPortKind `json:"kind"`

	// Name is the identifier for this port.
	Name string `json:"name"`

	// Description provides additional context.
	Description string `json:"description,omitempty"`

	// Schema is an optional reference to a JSON Schema.
	Schema string `json:"schema,omitempty"`

	// Required indicates if this input must be provided.
	Required bool `json:"required,omitempty"`

	// Sensitive marks data as containing PII or secrets.
	Sensitive bool `json:"sensitive,omitempty"`
}

type DataPortKind string

type DataPortMapping struct {
	// OutputPort is the source port name on the From entity.
	OutputPort string `json:"output_port"`
	// InputPort is the target port name on the To entity.
	InputPort string `json:"input_port"`
	// Transformation describes any data transformation applied.
	Transformation string `json:"transformation,omitempty"`
}

type DebugSession struct {
	// Executor runs the protocol.
	Executor *Executor

	// Context holds the execution state.
	Context *ExecutionContext

	// Breakpoints maps flow indices to breakpoints.
	Breakpoints map[int]*Breakpoint

	// Watchpoints maps entity IDs to watched state patterns.
	Watchpoints map[string]string
	// contains filtered or unexported fields
}

type DebugState struct {
	// FlowIndex is the current position in the protocol.
	FlowIndex int

	// StepsExecuted is the number of steps executed so far.
	StepsExecuted int

	// CurrentFlow is the next flow to be executed (nil if complete).
	CurrentFlow *Flow

	// EntityStates maps entity IDs to their current states.
	EntityStates map[string]string

	// IsCompleted indicates if execution has finished.
	IsCompleted bool

	// AtBreakpoint indicates if execution stopped at a breakpoint.
	AtBreakpoint bool

	// Error holds any execution error.
	Error error
}

type DependencyAnalysis struct {
	// EntityID is the step being analyzed.
	EntityID string `json:"entity_id"`

	// Name is the entity name.
	Name string `json:"name"`

	// StepType is the step type.
	StepType StepType `json:"step_type"`

	// DirectDependencies are steps that must complete before this one.
	DirectDependencies []string `json:"direct_dependencies"`

	// TransitiveDependencies are all upstream steps (direct and indirect).
	TransitiveDependencies []string `json:"transitive_dependencies"`

	// DirectDependents are steps that depend on this one.
	DirectDependents []string `json:"direct_dependents"`

	// TransitiveDependents are all downstream steps (direct and indirect).
	TransitiveDependents []string `json:"transitive_dependents"`

	// RequiredInputs lists required input ports.
	RequiredInputs []string `json:"required_inputs"`

	// ProducedOutputs lists output ports.
	ProducedOutputs []string `json:"produced_outputs"`

	// CriticalPath indicates if this step is on the critical path.
	CriticalPath bool `json:"critical_path"`
}

type DeploymentComponent struct {
	// ID is the unique identifier for this component.
	ID string `json:"id"`
	// Name is the human-readable display name.
	Name string `json:"name"`
	// Type classifies the component (e.g., "idp", "iga", "gateway", "mcp_client").
	Type string `json:"type"`
	// Description provides additional context.
	Description string `json:"description,omitempty"`
	// Entities lists the entity IDs contained in this component.
	Entities []string `json:"entities,omitempty"`
	// Implements lists the protocol roles this component implements.
	Implements []ProtocolRole `json:"implements,omitempty"`
	// Examples lists real-world products that represent this component type.
	Examples []string `json:"examples,omitempty"`
}

type Determinism string

type DiffCategory string

type DiffItem struct {
	// Type indicates whether the item was added, removed, or modified.
	Type DiffType `json:"type"`

	// Category classifies what was changed.
	Category DiffCategory `json:"category"`

	// Path identifies the location of the change (e.g., "entities[0]", "flows[2].action").
	Path string `json:"path"`

	// OldValue is the value before the change (nil for additions).
	OldValue interface{} `json:"old_value,omitempty"`

	// NewValue is the value after the change (nil for removals).
	NewValue interface{} `json:"new_value,omitempty"`

	// Summary is a human-readable description of the change.
	Summary string `json:"summary"`
}

type DiffOptions struct {
	// IgnoreMetadata skips metadata comparison.
	IgnoreMetadata bool

	// IgnoreDescriptions skips description field comparisons.
	IgnoreDescriptions bool

	// DeepFlowCompare enables detailed flow field comparison.
	DeepFlowCompare bool
}

type DiffSummary struct {
	// TotalChanges is the total number of differences.
	TotalChanges int `json:"total_changes"`

	// Added counts items that were added.
	Added int `json:"added"`

	// Removed counts items that were removed.
	Removed int `json:"removed"`

	// Modified counts items that were modified.
	Modified int `json:"modified"`

	// ByCategory breaks down changes by category.
	ByCategory map[DiffCategory]int `json:"by_category"`
}

type DiffType string

type Entity struct {
	// ID is the unique identifier used in flow references.
	ID string `json:"id"`

	// Name is the human-readable display name.
	Name string `json:"name"`

	// Type classifies the entity.
	Type EntityType `json:"type"`

	// Description of the entity's role.
	Description string `json:"description,omitempty"`

	// TrustLevel classifies the trust level of this entity.
	TrustLevel TrustLevel `json:"trust_level,omitempty"`

	// Metadata contains additional entity properties for rendering.
	Metadata *EntityMetadata `json:"metadata,omitempty"`

	// States defines the possible states for this entity.
	States []EntityState `json:"states,omitempty"`

	// ProtocolRoles defines the protocol-specific roles this entity implements.
	ProtocolRoles []ProtocolRole `json:"protocol_roles,omitempty"`

	// StepType classifies the processing nature (process profile).
	StepType StepType `json:"step_type,omitempty"`

	// Inputs defines input specifications (process profile).
	Inputs []DataPort `json:"inputs,omitempty"`

	// Outputs defines output specifications (process profile).
	Outputs []DataPort `json:"outputs,omitempty"`

	// Processing configures step execution (process profile).
	Processing *ProcessingConfig `json:"processing,omitempty"`

	// FailureModes lists possible failure scenarios (process profile).
	FailureModes []FailureMode `json:"failure_modes,omitempty"`

	// RetryStrategy configures retry behavior (process profile).
	RetryStrategy *RetryStrategy `json:"retry_strategy,omitempty"`

	// Parallel configures parallel execution for this step.
	Parallel *ParallelConfig `json:"parallel,omitempty"`
}

type EntityMetadata struct {
	// Network is the network boundary this entity belongs to.
	Network string `json:"network,omitempty"`
	// ServiceType classifies the service (e.g., "api", "database", "gateway").
	ServiceType string `json:"type,omitempty"`
}

type EntityState struct {
	// ID is the unique identifier for this state within the entity.
	ID string `json:"id"`

	// Name is the human-readable display name.
	Name string `json:"name,omitempty"`

	// Description provides additional context.
	Description string `json:"description,omitempty"`

	// Initial marks this as the initial state.
	Initial bool `json:"initial,omitempty"`

	// Final marks this as a terminal/final state.
	Final bool `json:"final,omitempty"`
}

type EntityType string

type ExecutionContext struct {
	// Protocol being executed.
	Protocol *Protocol

	// EntityStates maps entity ID to current state ID.
	EntityStates map[string]string

	// FlowIndex is the current position in the protocol's flows.
	FlowIndex int

	// Trace records execution history.
	Trace *ExecutionTrace

	// EventQueue holds pending events for event-driven execution.
	EventQueue []ExecutionEvent

	// Completed indicates execution has finished.
	Completed bool

	// Error holds any execution error.
	Error error
}

type ExecutionEvent struct {
	// Type categorizes the event.
	Type string `json:"type"`

	// FlowIndex references a specific flow (if applicable).
	FlowIndex int `json:"flow_index,omitempty"`

	// EntityID references a specific entity (if applicable).
	EntityID string `json:"entity_id,omitempty"`

	// Data holds event-specific payload.
	Data map[string]interface{} `json:"data,omitempty"`
}

type ExecutionGraph struct {
	// ProtocolID is the source protocol ID.
	ProtocolID string
	// Stages are ordered groups of steps that can execute in parallel.
	Stages []ExecutionStage
	// CriticalPath is the longest path through the graph.
	CriticalPath []string
	// EstimatedDuration is the estimated total execution time.
	EstimatedDuration time.Duration
}

type ExecutionMetrics struct {
	// Duration is the actual execution time.
	Duration time.Duration `json:"duration"`
	// InputTokens is the actual input token count.
	InputTokens int `json:"input_tokens,omitempty"`
	// OutputTokens is the actual output token count.
	OutputTokens int `json:"output_tokens,omitempty"`
	// APICallCount is the number of API calls made.
	APICallCount int `json:"api_call_count,omitempty"`
}

type ExecutionReadiness struct {
	// TotalSteps is the total number of process steps.
	TotalSteps int `json:"total_steps"`

	// ReadySteps is the number of steps ready to execute.
	ReadySteps int `json:"ready_steps"`

	// BlockedSteps is the number of blocked steps.
	BlockedSteps int `json:"blocked_steps"`

	// CompletedSteps is the number of completed steps.
	CompletedSteps int `json:"completed_steps"`

	// InProgressSteps is the number of steps currently executing.
	InProgressSteps int `json:"in_progress_steps"`

	// FailedSteps is the number of failed steps.
	FailedSteps int `json:"failed_steps"`

	// NextSteps lists the entity IDs of steps ready to execute.
	NextSteps []string `json:"next_steps"`

	// BlockedReasons maps blocked step IDs to their blocking reasons.
	BlockedReasons map[string][]string `json:"blocked_reasons"`
}

type ExecutionStage struct {
	// ID is the stage identifier.
	ID string
	// Steps are entity IDs that can execute in parallel at this stage.
	Steps []string
	// Dependencies are stage IDs that must complete before this stage.
	Dependencies []string
	// IsParallelBlock indicates this stage is an explicit parallel block.
	IsParallelBlock bool
	// ParallelConfig is the configuration for parallel execution.
	ParallelConfig *ParallelConfig
}

type ExecutionStep struct {
	// StepNumber is the 1-based step counter.
	StepNumber int `json:"step_number"`

	// FlowIndex is the index in Protocol.Flows.
	FlowIndex int `json:"flow_index"`

	// Timestamp when this step executed.
	Timestamp time.Time `json:"timestamp"`

	// From is the source entity ID.
	From string `json:"from"`

	// To is the target entity ID.
	To string `json:"to"`

	// Action is the flow action.
	Action string `json:"action"`

	// Label is the flow display label.
	Label string `json:"label,omitempty"`

	// Mode is the flow mode.
	Mode FlowMode `json:"mode,omitempty"`

	// Phase is the phase ID.
	Phase string `json:"phase,omitempty"`

	// Condition is the flow's condition (if any).
	Condition string `json:"condition,omitempty"`

	// ConditionMet indicates if condition was satisfied (for conditional flows).
	ConditionMet *bool `json:"condition_met,omitempty"`

	// StateChanges records state mutations from this step.
	StateChanges []StateChange `json:"state_changes,omitempty"`

	// Skipped indicates this flow was skipped (condition not met).
	Skipped bool `json:"skipped,omitempty"`

	// SkipReason explains why flow was skipped.
	SkipReason string `json:"skip_reason,omitempty"`
}

type ExecutionTrace struct {
	// ProtocolID identifies the executed protocol.
	ProtocolID string `json:"protocol_id"`

	// ProtocolName is the human-readable protocol name.
	ProtocolName string `json:"protocol_name"`

	// StartTime when execution began.
	StartTime time.Time `json:"start_time"`

	// EndTime when execution completed.
	EndTime time.Time `json:"end_time,omitempty"`

	// Steps records each executed flow.
	Steps []ExecutionStep `json:"steps"`

	// InitialStates captures entity states at start.
	InitialStates map[string]string `json:"initial_states,omitempty"`

	// FinalStates captures entity states at end.
	FinalStates map[string]string `json:"final_states,omitempty"`

	// Completed indicates if execution ran to completion.
	Completed bool `json:"completed"`

	// Error message if execution failed.
	Error string `json:"error,omitempty"`
}

type Executor struct {
	// Protocol to execute.
	Protocol *Protocol

	// ConditionEvaluator is called to evaluate flow conditions.
	// If nil, all conditions are assumed to be met.
	ConditionEvaluator func(ctx *ExecutionContext, flow *Flow) bool
}

type FailureMode struct {
	// ID is the unique identifier for this failure mode.
	ID string `json:"id"`

	// Name is the human-readable name.
	Name string `json:"name"`

	// Description explains the failure scenario.
	Description string `json:"description,omitempty"`

	// Severity indicates the impact level.
	Severity string `json:"severity,omitempty"`

	// Recovery describes how to handle this failure.
	Recovery string `json:"recovery,omitempty"`
}

type FileValidationResult struct {
	Filename string
	Protocol *Protocol
	Errors   ValidationErrors
	ParseErr error
}

type Flow struct {
	// From is the source entity ID.
	From string `json:"from"`

	// To is the target entity ID.
	To string `json:"to"`

	// Action identifies the action being performed.
	Action string `json:"action"`

	// Label is the display label (defaults to Action).
	Label string `json:"label,omitempty"`

	// Mode is the interaction mode.
	Mode FlowMode `json:"mode,omitempty"`

	// Phase is the phase ID this flow belongs to.
	Phase string `json:"phase,omitempty"`

	// Description provides additional details.
	Description string `json:"description,omitempty"`

	// Sequence provides explicit ordering.
	Sequence int `json:"sequence,omitempty"`

	// Condition specifies when this flow is executed (e.g., "token_valid", "error").
	Condition string `json:"condition,omitempty"`

	// Note is a visible annotation displayed on the diagram.
	Note string `json:"note,omitempty"`

	// Annotations are typed annotations for tooling and documentation.
	Annotations []Annotation `json:"annotations,omitempty"`

	// Alternatives are alternative paths from this flow point.
	Alternatives []Alternative `json:"alternatives,omitempty"`

	// Animation configures animation for this flow in animated SVG output.
	// Can be a string (preset name) or FlowAnimation object.
	Animation *FlowAnimation `json:"animation,omitempty"`

	// Sets defines state mutations that occur when this flow executes.
	Sets []StateMutation `json:"sets,omitempty"`

	// Security specifies security requirements for this flow.
	Security *FlowSecurity `json:"security,omitempty"`

	// DataMappings explicitly maps output ports to input ports for data lineage.
	DataMappings []DataPortMapping `json:"data_mappings,omitempty"`
}

type FlowAnimation struct {
	// Enabled controls whether this flow is animated. Defaults to true.
	Enabled *bool `json:"enabled,omitempty"`

	// Preset is a semantic preset name (request, success, error, warning, highlight, none).
	Preset AnimationPreset `json:"preset,omitempty"`

	// Duration is the animation cycle duration (e.g., "2s", "1.5s").
	Duration string `json:"duration,omitempty"`

	// Delay is the animation start delay (e.g., "0.5s").
	Delay string `json:"delay,omitempty"`

	// DotColor is the animated dot fill color.
	DotColor string `json:"dot_color,omitempty"`

	// DotSize is the animated dot radius in pixels.
	DotSize int `json:"dot_size,omitempty"`

	// Pulse adds a pulsing effect (useful for errors/warnings).
	Pulse bool `json:"pulse,omitempty"`

	// Easing is the CSS easing function (linear, ease-in-out, etc.).
	Easing string `json:"easing,omitempty"`
}

type FlowListItem struct {
	Index         int
	Flow          *Flow
	IsCurrent     bool
	HasBreakpoint bool
	IsExecuted    bool
}

type FlowMode string

type FlowSecurity struct {
	// Requires lists security mechanisms required for this flow.
	Requires []SecurityRequirement `json:"requires,omitempty"`
	// Token is the token definition ID used for this flow.
	Token string `json:"token,omitempty"`
	// Confidential indicates if the flow carries sensitive data.
	Confidential bool `json:"confidential,omitempty"`
	// Description provides additional security context.
	Description string `json:"description,omitempty"`
}

type JoinCondition string

type LatencyBudget struct {
	// P50 is the 50th percentile latency target.
	P50 string `json:"p50,omitempty"`
	// P95 is the 95th percentile latency target.
	P95 string `json:"p95,omitempty"`
	// P99 is the 99th percentile latency target.
	P99 string `json:"p99,omitempty"`
	// Max is the maximum acceptable latency (hard limit).
	Max string `json:"max,omitempty"`
	// ExpectedLatency is the expected typical latency.
	ExpectedLatency string `json:"expected_latency,omitempty"`
	// Critical marks this step as on the critical path.
	Critical bool `json:"critical,omitempty"`
	// VarianceClass indicates latency variability (low, medium, high).
	VarianceClass LatencyVarianceClass `json:"variance_class,omitempty"`
}

type LatencyBudgetViolation struct {
	// EntityID is the violating entity.
	EntityID string `json:"entity_id"`
	// Metric is the violated metric (p50, p95, p99, max).
	Metric string `json:"metric"`
	// Budget is the budgeted latency.
	Budget time.Duration `json:"budget"`
	// Estimated is the estimated latency.
	Estimated time.Duration `json:"estimated"`
	// Severity indicates the violation severity.
	Severity string `json:"severity"`
}

type LatencyEstimate struct {
	// EntityID is the entity this estimate is for (empty for total).
	EntityID string `json:"entity_id,omitempty"`
	// P50 is the 50th percentile latency.
	P50 time.Duration `json:"p50"`
	// P95 is the 95th percentile latency.
	P95 time.Duration `json:"p95"`
	// P99 is the 99th percentile latency.
	P99 time.Duration `json:"p99"`
	// Max is the maximum expected latency.
	Max time.Duration `json:"max"`
	// Expected is the expected typical latency.
	Expected time.Duration `json:"expected"`
	// VarianceClass indicates the latency variability.
	VarianceClass LatencyVarianceClass `json:"variance_class"`
	// OnCriticalPath indicates if this step is on the critical path.
	OnCriticalPath bool `json:"on_critical_path"`
}

type LatencyMeasurement struct {
	// EntityID is the entity that was measured.
	EntityID string `json:"entity_id"`
	// Duration is the actual execution duration.
	Duration time.Duration `json:"duration"`
	// ExceedsP50 indicates if duration exceeded P50 budget.
	ExceedsP50 bool `json:"exceeds_p50,omitempty"`
	// ExceedsP95 indicates if duration exceeded P95 budget.
	ExceedsP95 bool `json:"exceeds_p95,omitempty"`
	// ExceedsP99 indicates if duration exceeded P99 budget.
	ExceedsP99 bool `json:"exceeds_p99,omitempty"`
	// ExceedsMax indicates if duration exceeded Max budget.
	ExceedsMax bool `json:"exceeds_max,omitempty"`
}

type LatencyVarianceClass string

type LineageEdge struct {
	// SourceEntity is the ID of the entity providing the data.
	SourceEntity string `json:"source_entity"`
	// SourcePort is the name of the output port.
	SourcePort string `json:"source_port"`
	// TargetEntity is the ID of the entity consuming the data.
	TargetEntity string `json:"target_entity"`
	// TargetPort is the name of the input port.
	TargetPort string `json:"target_port"`
	// FlowIndex is the index of the flow that creates this connection.
	FlowIndex int `json:"flow_index"`
	// Transformation describes any data transformation applied.
	Transformation string `json:"transformation,omitempty"`
}

type NetworkConfig struct {
	// Name is the display name for the boundary.
	Name string `json:"name,omitempty"`
	// Style is the visual style: trusted, dmz, external, cloud.
	Style string `json:"style,omitempty"`
	// Entities explicitly lists entity IDs in this boundary.
	Entities []string `json:"entities,omitempty"`
	// Description provides tooltip/hover text.
	Description string `json:"description,omitempty"`
	// Color overrides the default boundary color.
	Color string `json:"color,omitempty"`
}

type NetworkLayoutConfig struct {
	// Direction is the layout direction: horizontal or vertical.
	Direction string `json:"direction,omitempty"`
	// Order specifies the boundary ordering.
	Order []string `json:"order,omitempty"`
}

type ParallelBlock struct {
	// ID is the unique identifier for this block.
	ID string
	// ForkEntity is the entity that starts the parallel execution.
	ForkEntity string
	// JoinEntity is the entity that collects results (if any).
	JoinEntity string
	// Branches are the parallel branches.
	Branches []ParallelBranch
	// Mode is the parallel execution mode.
	Mode ParallelMode
	// JoinCondition specifies completion criteria.
	JoinCondition JoinCondition
}

type ParallelBranch struct {
	// ID is the unique identifier for this branch.
	ID string `json:"id"`
	// Name is the human-readable name.
	Name string `json:"name,omitempty"`
	// EntityID is the target entity for this branch (optional).
	EntityID string `json:"entity_id,omitempty"`
	// FlowRefs lists flow indices that belong to this branch.
	FlowRefs []int `json:"flow_refs,omitempty"`
	// Condition specifies when this branch is executed.
	Condition string `json:"condition,omitempty"`
	// Weight for load balancing in scatter mode.
	Weight float64 `json:"weight,omitempty"`
}

type ParallelConfig struct {
	// Mode specifies the parallel execution mode.
	Mode ParallelMode `json:"mode"`
	// Branches lists the parallel branches (entity IDs or flow groups).
	Branches []ParallelBranch `json:"branches,omitempty"`
	// JoinCondition specifies when parallel execution is considered complete.
	JoinCondition JoinCondition `json:"join_condition,omitempty"`
	// MaxConcurrency limits the number of concurrent executions.
	MaxConcurrency int `json:"max_concurrency,omitempty"`
	// Timeout for the entire parallel block.
	Timeout string `json:"timeout,omitempty"`
}

type ParallelMode string

type Phase struct {
	// ID is the unique identifier.
	ID string `json:"id"`

	// Name is the human-readable name.
	Name string `json:"name"`

	// Description of the phase.
	Description string `json:"description,omitempty"`

	// Parent is the ID of the parent phase for nested phases.
	Parent string `json:"parent,omitempty"`
}

type PortReference struct {
	// EntityID is the ID of the entity.
	EntityID string `json:"entity_id"`
	// PortName is the name of the port.
	PortName string `json:"port_name"`
	// PortKind indicates if this is an input or output port.
	PortKind string `json:"port_kind"` // "input" or "output"
	// Sensitive indicates if the port handles sensitive data.
	Sensitive bool `json:"sensitive,omitempty"`
}

type PortSchemaValidator struct {
	// contains filtered or unexported fields
}

type ProcessCostAnalysis struct {
	// ProtocolID is the source protocol.
	ProtocolID string `json:"protocol_id"`
	// TotalEstimate is the total estimated cost.
	TotalEstimate CostEstimate `json:"total_estimate"`
	// StepEstimates are per-step cost estimates.
	StepEstimates []CostEstimate `json:"step_estimates"`
	// CostByType shows costs grouped by step type.
	CostByType map[StepType]float64 `json:"cost_by_type"`
	// CriticalPathCost is the cost of the critical path.
	CriticalPathCost float64 `json:"critical_path_cost"`
	// ParallelSavings is estimated savings from parallelization.
	ParallelSavings float64 `json:"parallel_savings,omitempty"`
}

type ProcessExecutionContext struct {
	*ExecutionContext

	// AvailableInputs tracks which data ports have data available.
	// Key is "entityID.portName", value is true if available.
	AvailableInputs map[string]bool

	// ProducedOutputs tracks which outputs have been produced.
	// Key is "entityID.portName", value is true if produced.
	ProducedOutputs map[string]bool

	// BlockedSteps tracks which steps are blocked and why.
	BlockedSteps map[string][]string // entityID -> list of missing inputs

	// ExecutionOrder is the topologically sorted execution order.
	ExecutionOrder []string

	// StepStatus tracks the status of each step.
	StepStatus map[string]StepExecutionStatus
}

type ProcessExecutor struct {
	*Executor

	// DataFlowGraph maps entity outputs to consuming entity inputs.
	// Key is "sourceEntityID.outputName", value is list of "targetEntityID.inputName".
	DataFlowGraph map[string][]string

	// Dependencies maps entity ID to its required predecessor entity IDs.
	Dependencies map[string][]string

	// Dependents maps entity ID to entities that depend on it.
	Dependents map[string][]string
}

type ProcessLatencyAnalysis struct {
	// ProtocolID is the source protocol.
	ProtocolID string `json:"protocol_id"`
	// TotalLatency is the estimated end-to-end latency.
	TotalLatency LatencyEstimate `json:"total_latency"`
	// StepLatencies are per-step latency estimates.
	StepLatencies []LatencyEstimate `json:"step_latencies"`
	// CriticalPathLatency is the latency of the critical path.
	CriticalPathLatency LatencyEstimate `json:"critical_path_latency"`
	// CriticalPath is the list of entity IDs on the critical path.
	CriticalPath []string `json:"critical_path"`
	// ParallelSavings is the latency saved by parallel execution.
	ParallelSavings time.Duration `json:"parallel_savings"`
	// BudgetViolations lists steps exceeding their latency budget.
	BudgetViolations []LatencyBudgetViolation `json:"budget_violations,omitempty"`
	// LatencyByType shows latencies grouped by step type.
	LatencyByType map[StepType]time.Duration `json:"latency_by_type"`
}

type ProcessingConfig struct {
	// Engine identifies the processing engine.
	Engine string `json:"engine,omitempty"`

	// Determinism indicates processing predictability.
	Determinism Determinism `json:"determinism,omitempty"`

	// ModelPolicy specifies model selection for LLM steps.
	ModelPolicy string `json:"model_policy,omitempty"`

	// Timeout is the maximum processing duration.
	Timeout string `json:"timeout,omitempty"`

	// Idempotent indicates if repeated execution is safe.
	Idempotent bool `json:"idempotent,omitempty"`

	// Cacheable indicates if outputs can be cached.
	Cacheable bool `json:"cacheable,omitempty"`

	// CacheTTL is the cache time-to-live if cacheable.
	CacheTTL string `json:"cache_ttl,omitempty"`

	// CostModel specifies the cost tracking model for this step.
	CostModel *CostModel `json:"cost_model,omitempty"`

	// LatencyBudget specifies timing SLIs for this step.
	LatencyBudget *LatencyBudget `json:"latency_budget,omitempty"`
}

type Protocol struct {
	// ProtocolMeta contains metadata about the protocol.
	ProtocolMeta ProtocolMeta `json:"protocol"`

	// Extends specifies a base protocol to extend.
	Extends *ProtocolExtends `json:"extends,omitempty"`

	// Imports specifies other protocol files to import from.
	Imports []ProtocolImport `json:"imports,omitempty"`

	// Entities are the participants in the protocol (systems, actors, services).
	Entities []Entity `json:"entities"`

	// Phases provide optional logical grouping of flows.
	Phases []Phase `json:"phases,omitempty"`

	// Flows are the interactions between entities.
	Flows []Flow `json:"flows"`

	// Metadata contains additional protocol-level configuration.
	Metadata *ProtocolMetadata `json:"metadata,omitempty"`
	// contains filtered or unexported fields
}

type ProtocolDiff struct {
	// BaseProtocolID is the ID of the base protocol.
	BaseProtocolID string `json:"base_protocol_id"`

	// NewProtocolID is the ID of the new protocol.
	NewProtocolID string `json:"new_protocol_id"`

	// Items contains all differences found.
	Items []DiffItem `json:"items"`

	// Summary provides aggregate statistics.
	Summary DiffSummary `json:"summary"`
}

type ProtocolExtends struct {
	// Path is the file path to the base protocol (relative to current file).
	Path string `json:"path"`

	// ExcludeEntities lists entity IDs from the base to exclude.
	ExcludeEntities []string `json:"exclude_entities,omitempty"`

	// ExcludePhases lists phase IDs from the base to exclude.
	ExcludePhases []string `json:"exclude_phases,omitempty"`

	// ExcludeFlows lists flow indices from the base to exclude.
	ExcludeFlows []int `json:"exclude_flows,omitempty"`
}

type ProtocolImport struct {
	// Path is the file path to import (relative to current file).
	Path string `json:"path"`

	// Alias prefixes imported IDs to avoid collisions (e.g., "oauth_").
	Alias string `json:"alias,omitempty"`

	// Entities lists specific entity IDs to import (empty = all).
	Entities []string `json:"entities,omitempty"`

	// Phases lists specific phase IDs to import (empty = none unless entities need them).
	Phases []string `json:"phases,omitempty"`

	// IncludeFlows imports flows between the specified entities.
	IncludeFlows bool `json:"include_flows,omitempty"`
}

type ProtocolKind string

type ProtocolMeta struct {
	// ID is the unique identifier for the protocol.
	ID string `json:"id"`

	// Name is the human-readable name.
	Name string `json:"name"`

	// Kind identifies the PIDL profile type (protocol or process).
	Kind ProtocolKind `json:"kind,omitempty"`

	// Version of this protocol description.
	Version string `json:"version,omitempty"`

	// Description provides a brief summary.
	Description string `json:"description,omitempty"`

	// Category classifies the protocol type.
	Category Category `json:"category,omitempty"`

	// References links to relevant specifications.
	References []Reference `json:"references,omitempty"`
}

type ProtocolMetadata struct {
	// Networks defines network boundary configurations.
	Networks map[string]*NetworkConfig `json:"networks,omitempty"`
	// NetworkLayout configures network diagram layout.
	NetworkLayout *NetworkLayoutConfig `json:"network_layout,omitempty"`
	// Tokens defines token types used in the protocol.
	Tokens []TokenDefinition `json:"tokens,omitempty"`
	// Components defines logical deployment components.
	Components []DeploymentComponent `json:"components,omitempty"`
	// TrustRelations defines trust relationships between entities or components.
	TrustRelations []TrustRelationship `json:"trust_relations,omitempty"`
}

type ProtocolRole struct {
	// Protocol is the protocol identifier (e.g., "oauth", "scim", "aauth", "authzen", "mcp", "a2a", "spiffe").
	Protocol string `json:"protocol"`
	// Role is the role within that protocol (e.g., "authorization_server", "client", "pep", "pdp").
	Role string `json:"role"`
	// Variant is an optional sub-role or variant (e.g., "person_server" vs "access_server" for AAuth).
	Variant string `json:"variant,omitempty"`
	// Description provides additional context.
	Description string `json:"description,omitempty"`
}

type Reference struct {
	// Name of the reference (e.g., "RFC 6749").
	Name string `json:"name"`

	// URL to the reference.
	URL string `json:"url"`
}

type ResolveOptions struct {
	// BasePath is the directory to resolve relative paths from.
	BasePath string

	// MaxDepth limits import nesting depth (default: 10).
	MaxDepth int
}

type RetryStrategy struct {
	// MaxAttempts is the maximum number of retry attempts.
	MaxAttempts int `json:"max_attempts,omitempty"`

	// InitialDelay is the delay before the first retry.
	InitialDelay string `json:"initial_delay,omitempty"`

	// MaxDelay is the maximum delay between retries.
	MaxDelay string `json:"max_delay,omitempty"`

	// BackoffMultiplier increases delay between retries.
	BackoffMultiplier float64 `json:"backoff_multiplier,omitempty"`

	// RetryOn lists failure mode IDs that trigger retry.
	RetryOn []string `json:"retry_on,omitempty"`
}

type SchemaRegistry struct {
	// contains filtered or unexported fields
}

type SchemaValidationError struct {
	// Path is the JSON path to the invalid field.
	Path string
	// Message describes the validation failure.
	Message string
	// SchemaPath is the path in the schema that failed.
	SchemaPath string
}

type SchemaValidationResult struct {
	// Valid indicates if the data passed validation.
	Valid bool
	// Errors contains validation error messages.
	Errors []SchemaValidationError
}

type SecurityRequirement string

type StateChange struct {
	// Entity is the entity ID.
	Entity string `json:"entity"`

	// FromState is the prior state (empty if not tracked).
	FromState string `json:"from_state,omitempty"`

	// ToState is the new state.
	ToState string `json:"to_state"`
}

type StateMutation struct {
	// Entity is the ID of the entity whose state changes.
	Entity string `json:"entity"`

	// To is the target state ID.
	To string `json:"to"`

	// From is the optional required prior state (for validation).
	From string `json:"from,omitempty"`
}

type StateTransition struct {
	// EntityID is the entity undergoing the state change.
	EntityID string
	// FromState is the prior state (empty if not specified).
	FromState string
	// ToState is the target state.
	ToState string
	// FlowAction is the action that triggers this transition.
	FlowAction string
	// FlowLabel is the display label for the triggering flow.
	FlowLabel string
}

type StepExecutionStatus string

type StepType string

type TokenDefinition struct {
	// ID is the unique identifier for this token definition.
	ID string `json:"id"`
	// Name is the human-readable display name.
	Name string `json:"name,omitempty"`
	// Type is the token type: jwt, opaque, saml, api_key.
	Type string `json:"type,omitempty"`
	// Issuer is the entity ID that issues this token.
	Issuer string `json:"issuer,omitempty"`
	// Audience is the entity ID that consumes this token.
	Audience string `json:"audience,omitempty"`
	// Binding is the token binding method: bearer, mtls, dpop.
	Binding string `json:"binding,omitempty"`
	// Description provides additional context.
	Description string `json:"description,omitempty"`
}

type TrustLevel string

type TrustRelationship struct {
	// ID is an optional unique identifier for this relationship.
	ID string `json:"id,omitempty"`
	// From is the source entity or component ID.
	From string `json:"from"`
	// To is the target entity or component ID.
	To string `json:"to"`
	// Type is the relationship type (e.g., "authenticates", "validates", "delegates").
	Type string `json:"type"`
	// Credentials lists what credentials are exchanged in this relationship.
	Credentials []string `json:"credentials,omitempty"`
	// Mutual indicates if this is a bidirectional trust (e.g., mTLS).
	Mutual bool `json:"mutual,omitempty"`
	// Description provides additional context.
	Description string `json:"description,omitempty"`
}

type ValidationError struct {
	Field   string
	Message string
}

type ValidationErrors []ValidationError