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 BinaryBody struct {
	Base64    string `json:"base64"`
	MediaType string `json:"mediaType,omitempty"`
}

type Binding struct {
	// Format names the format and its major version: pidl-binding/v1.
	Format string `json:"format"`

	// Participants maps a document participant ID to how a capture names it.
	Participants map[string]BindingParticipant `json:"participants"`

	// LabelsByPath resolves a generic sender label, such as a trace's
	// "client", by the request path.
	LabelsByPath []BindingLabelRule `json:"labelsByPath,omitempty"`

	// Paths gives, per participant, the path of a step where the
	// deployment's path differs from the document's example. Keys are step
	// keys, as in Steps.
	Paths map[string]map[string]string `json:"paths,omitempty"`

	// Rewrite rewrites every exchange's URL before matching, in order.
	Rewrite []BindingRewrite `json:"rewrite,omitempty"`

	// Unobservable lists participants a capture cannot see, in addition to
	// those whose role type is user.
	Unobservable []string `json:"unobservable,omitempty"`

	// Steps replaces a step's rule for this deployment. A key names, from
	// most to least specific: "<scenario>/<expanded-id>", the step in one
	// scenario as the walkthrough qualifies it ("ps-authorization/consent.poll");
	// "<defining-scenario>/<flow-id>", the flow wherever it appears, as
	// sample sets address steps ("consent/poll"); or "*/<flow-id>", any flow
	// with that ID. Step IDs repeat across scenarios, so a bare ID is not a key.
	Steps map[string]BindingStep `json:"steps,omitempty"`
}

type BindingLabelRule struct {
	// Label is the sender label the rule applies to, such as "client".
	Label string `json:"label"`
	// Path is a regular expression the request path must match.
	Path string `json:"path"`
	// Participant is the participant the sender is taken to be.
	Participant string `json:"participant"`
}

type BindingParticipant struct {
	// Labels are the capturing tool's names for the participant.
	Labels []string `json:"labels,omitempty"`
	// Hosts are the host names the participant answers at.
	Hosts []string `json:"hosts,omitempty"`
}

type BindingRewrite struct {
	// Match is a regular expression over the whole URL.
	Match string `json:"match"`
	// To is the replacement, with $1-style references to Match's groups.
	To string `json:"to"`
}

type BindingStep struct {
	Match StepMatch `json:"match"`
}

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 Briefing struct {
	// Why explains, as prose, why the scenario exists and what problem it
	// solves.
	Why string `json:"why,omitempty"`

	// Points are the key points, in display order.
	Points []string `json:"points,omitempty"`

	// Narration is spoken over the briefing.
	Narration Narration `json:"narration,omitempty"`
}

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 ExampleHeader struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

type ExampleKind string

type ExampleRequest struct {
	Method  string          `json:"method"`
	URL     string          `json:"url"`
	Headers []ExampleHeader `json:"headers,omitempty"`
	// Body is the request body as JSON, kept byte for byte so key order
	// survives a round trip.
	Body json.RawMessage `json:"body,omitempty"`
}

type ExampleResponse struct {
	Status  int             `json:"status"`
	Headers []ExampleHeader `json:"headers,omitempty"`
	Body    json.RawMessage `json:"body,omitempty"`
}

type ExampleToken struct {
	// Token is the token definition ID.
	Token string `json:"token"`
	// Label says where the token travels, such as "Signature-Key header".
	Label string `json:"label,omitempty"`
	// Header and Payload are the decoded JWT header and claims.
	Header  json.RawMessage `json:"header,omitempty"`
	Payload json.RawMessage `json:"payload,omitempty"`
}

type Exchange struct {
	// Time is when the request was made. A tool that has no clock keeps the
	// order and leaves it unset.
	Time *time.Time `json:"time,omitempty"`

	// From and To are the capturing tool's labels for the sender and the
	// receiver, kept as written. A binding maps them to participants.
	From string `json:"from,omitempty"`
	To   string `json:"to,omitempty"`

	// RequestID is the value of a request ID header, when the capture has
	// one. It joins client events and other sources to the exchange.
	RequestID string `json:"requestId,omitempty"`

	Request  ObservedRequest  `json:"request"`
	Response ObservedResponse `json:"response"`

	// BodyTruncated reports that a body was cut at the size limit.
	BodyTruncated bool `json:"bodyTruncated,omitempty"`

	// Label is a name a tool gave the exchange, such as a Newman request's
	// name. It never changes a match.
	Label string `json:"label,omitempty"`

	// Annotations are evidence a tool produced about the exchange, such as
	// assertions or a client's own events. They never change a match.
	Annotations []ExchangeAnnotation `json:"annotations,omitempty"`
}

type ExchangeAnnotation struct {
	// Kind classifies the annotation, such as "assertion" or "client-event".
	Kind string `json:"kind"`

	// Text is the annotation as a person reads it.
	Text string `json:"text"`

	// OK is the result of an assertion; unset for other kinds.
	OK *bool `json:"ok,omitempty"`

	// Time is when the annotated event happened, when it differs from the
	// exchange's time.
	Time *time.Time `json:"time,omitempty"`
}

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 Finding struct {
	ID          string `json:"id"`
	Severity    string `json:"severity"`
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`
	Location    string `json:"location,omitempty"`
}

type Flow struct {
	// ID identifies the step within its scenario, for deep links, samples
	// and narration. It is optional, unique within the scenario, and
	// stable when steps are added or moved.
	ID string `json:"id,omitempty"`

	// Narration is spoken for this step, keyed by language. Without it,
	// tools fall back to Description.
	Narration Narration `json:"narration,omitempty"`

	// Representations override the narration when the step is viewed as
	// "http", "curl" or a sample language.
	Representations map[string]RepresentationNarration `json:"representations,omitempty"`

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

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

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

	// Include is the ID of a fragment scenario whose flows take this
	// step's place. An include step has no From, To or Action.
	Include string `json:"include,omitempty"`

	// 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 is a display-only step number. It never affects order:
	// flows run in array order.
	//
	// Deprecated: move the flow within the flows array to change its order.
	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"`

	// Verification records the evidentiary provenance/tier of this flow.
	Verification *FlowVerification `json:"verification,omitempty"`

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

	// Example is an illustrative request, response and decoded tokens for
	// this step, used by walkthrough viewers.
	Example *FlowExample `json:"example,omitempty"`

	// Match is the rule that says which observed exchanges are this step,
	// when the example's method, path and status are not enough or the
	// step has no example request. A binding can replace it for one
	// deployment.
	Match *StepMatch `json:"match,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 FlowExample struct {
	// Source cites where the example comes from, such as "draft-11 §7.2.1".
	Source string `json:"source"`

	// Kind is draft or derived.
	Kind ExampleKind `json:"kind"`

	// Request is the HTTP request, for steps that send one.
	Request *ExampleRequest `json:"request,omitempty"`

	// Response is the HTTP response, for steps that return one.
	Response *ExampleResponse `json:"response,omitempty"`

	// Tokens are decoded tokens the message carries, in display order.
	Tokens []ExampleToken `json:"tokens,omitempty"`

	// Samples are code that sends or handles this message, such as SDK
	// calls, shown beside the HTTP form.
	Samples []Sample `json:"samples,omitempty"`

	// Note explains anything the reader should notice in this example.
	Note string `json:"note,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"`
	// SignedBy is the entity that signs the request. It defaults to the
	// flow's From entity; set it when someone else signs, for example an
	// intermediary signing on an agent's behalf.
	SignedBy string `json:"signed_by,omitempty"`
	// Issues lists token definition IDs this flow delivers.
	Issues []string `json:"issues,omitempty"`
	// Verifies lists token definition IDs the receiver checks.
	Verifies []string `json:"verifies,omitempty"`
}

type FlowVerification struct {
	Tier     VerificationTier `json:"tier"`
	Source   string           `json:"source,omitempty"`   // e.g. "OpenAI technical report", "METR"
	Citation string           `json:"citation,omitempty"` // URL or reference locating the source
}

type Group struct {
	// ID is the unique identifier scenarios refer to.
	ID string `json:"id"`

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

	// Description of the group.
	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 Narration map[string]string

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 Observation struct {
	// Format names the format and its major version: pidl-observation/v1.
	Format string `json:"format"`

	// Source says which tool produced the observation and what it covers.
	Source ObservationSource `json:"source"`

	// Exchanges are the requests and responses, in the order they happened.
	Exchanges []Exchange `json:"exchanges"`
}

type ObservationSource struct {
	// Tool names the tool that captured the exchanges, such as
	// "aauth-sandbox", "har" or "newman".
	Tool string `json:"tool"`

	// RequestFidelity is wire or client; empty when unknown.
	RequestFidelity RequestFidelity `json:"requestFidelity,omitempty"`

	// From and To bound the time the observation covers.
	From *time.Time `json:"from,omitempty"`
	To   *time.Time `json:"to,omitempty"`
}

type ObservedExtra struct {
	// AfterStep is the number of the step it followed, or 0 when it came
	// before the first matched step.
	AfterStep int `json:"after_step"`
	// From and To are the participants, when the binding resolved them.
	From     string          `json:"from,omitempty"`
	To       string          `json:"to,omitempty"`
	Observed ObservedMessage `json:"observed"`
}

type ObservedHeaders [][2]string

type ObservedMessage struct {
	Time *time.Time `json:"time,omitempty"`
	// From and To are the capturing tool's labels for sender and receiver.
	From string `json:"from,omitempty"`
	To   string `json:"to,omitempty"`
	// RequestID is the value of a request ID header, when the capture has one.
	RequestID string           `json:"request_id,omitempty"`
	Request   *ExampleRequest  `json:"request,omitempty"`
	Response  *ExampleResponse `json:"response,omitempty"`
	// Tokens are the tokens found in the message, decoded and not verified.
	Tokens []ExampleToken `json:"tokens,omitempty"`
	// Label and Annotations are evidence the capturing tool recorded.
	Label       string               `json:"label,omitempty"`
	Annotations []ExchangeAnnotation `json:"annotations,omitempty"`
	// Repeats is how many exchanges a repeated step took, when more than one.
	Repeats int `json:"repeats,omitempty"`
	// BodyTruncated reports that a body was cut at the capture's size limit.
	BodyTruncated bool `json:"body_truncated,omitempty"`
}

type ObservedRequest struct {
	Method  string          `json:"method"`
	URL     string          `json:"url"`
	Headers ObservedHeaders `json:"headers,omitempty"`
	// Body is a JSON value for a JSON body, a JSON string for other text,
	// or {"base64": "…", "mediaType": "…"} for binary content.
	Body json.RawMessage `json:"body,omitempty"`
}

type ObservedResponse struct {
	Status  int             `json:"status"`
	Headers ObservedHeaders `json:"headers,omitempty"`
	// Body is encoded as ObservedRequest.Body is.
	Body json.RawMessage `json:"body,omitempty"`
}

type ObservedRun struct {
	// Scenario is the ID of the scenario this entry is an instance of.
	Scenario string `json:"scenario"`
	// Source names the tool that captured the run; RequestFidelity says
	// whether its requests are the wire messages or a client's.
	Source          string          `json:"source"`
	RequestFidelity RequestFidelity `json:"request_fidelity,omitempty"`
	// Instance is this instance's number, from 1, of Instances found.
	Instance  int `json:"instance"`
	Instances int `json:"instances"`
	// From and To bound the instance's exchanges in time.
	From *time.Time `json:"from,omitempty"`
	To   *time.Time `json:"to,omitempty"`
	// RunnerUp is the next-best scenario at this point of the capture.
	RunnerUp string `json:"runner_up,omitempty"`
	// Counts of step outcomes; Matched counts every matched step and Weak
	// the matched steps that are weak. Explained counts exchanges matched
	// to steps and Extra those that matched none.
	Matched      int `json:"matched"`
	Weak         int `json:"weak"`
	NotSeen      int `json:"not_seen"`
	Skipped      int `json:"skipped"`
	Unmatchable  int `json:"unmatchable"`
	Unobservable int `json:"unobservable"`
	Explained    int `json:"explained"`
	Extra        int `json:"extra"`
	// Redacted reports that raw token, signature and credential values
	// were masked.
	Redacted bool `json:"redacted"`
}

type Outline struct {
	ID          string            `json:"id"`
	Name        string            `json:"name"`
	Description string            `json:"description,omitempty"`
	Roles       []OutlineRole     `json:"roles"`
	Groups      []Group           `json:"groups,omitempty"`
	Scenarios   []OutlineScenario `json:"scenarios"`
	Tokens      []OutlineToken    `json:"tokens,omitempty"`
}

type OutlineRole struct {
	Position    int    `json:"position"`
	ID          string `json:"id"`
	Name        string `json:"name"`
	Type        string `json:"type,omitempty"`
	Description string `json:"description,omitempty"`
}

type OutlineScenario struct {
	Position     int           `json:"position"`
	ID           string        `json:"id"`
	Name         string        `json:"name"`
	Description  string        `json:"description,omitempty"`
	Fragment     bool          `json:"fragment,omitempty"`
	Group        string        `json:"group,omitempty"`
	VariantOf    string        `json:"variant_of,omitempty"`
	VariantLabel string        `json:"variant_label,omitempty"`
	Participants []string      `json:"participants"`
	Steps        []OutlineStep `json:"steps"`
}

type OutlineStep struct {
	Number   int    `json:"number"`
	From     string `json:"from,omitempty"`
	To       string `json:"to,omitempty"`
	Label    string `json:"label"`
	Response bool   `json:"response,omitempty"`
	Phase    string `json:"phase,omitempty"`
	// Include is the fragment ID for an include step, and IncludePosition
	// its position among the outline's scenarios.
	Include         string `json:"include,omitempty"`
	IncludePosition int    `json:"include_position,omitempty"`
}

type OutlineToken struct {
	ID         string   `json:"id"`
	Name       string   `json:"name"`
	Issuer     string   `json:"issuer,omitempty"`
	Audience   string   `json:"audience,omitempty"`
	VerifiedBy []string `json:"verified_by,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 ProjectOptions struct {
	// Expand replaces include steps with the included fragment's flows,
	// recursively. When false, include steps are kept so renderers can
	// draw them as a labeled box.
	Expand bool
}

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. A document has either
	// Flows (a single unnamed scenario) or Scenarios, not both.
	Flows []Flow `json:"flows,omitempty"`

	// Pronunciations map a term to its spoken form per language, such as
	// {"agent_jkt": {"en-US": "agent J K T"}}, in the shape videoascode
	// reads. Entries are looked up by term, never listed in order.
	Pronunciations map[string]map[string]string `json:"pronunciations,omitempty"`

	// Groups are ordered sections for navigation, such as "Signing" or
	// "Access modes". Scenarios name their group; group order, then
	// scenario order within a group, sets the output order.
	Groups []Group `json:"groups,omitempty"`

	// Scenarios are named, ordered sequences of flows. Array position is
	// the scenario order.
	Scenarios []Scenario `json:"scenarios,omitempty"`

	// Fragments holds the fragment scenarios that include steps in a
	// collapsed projection refer to, so renderers can label and size the
	// include boxes. Protocol.Scenario sets it; it is never serialized.
	Fragments []Scenario `json:"-"`

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