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 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 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 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"`
}

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 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 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"`
}

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 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 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 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 ProtocolMeta struct {
	// ID is the unique identifier for the protocol.
	ID string `json:"id"`

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

	// 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 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 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