ux

type AuditLogger interface {
	// LogVerificationAttempt logs a verification attempt.
	//
	// # Inputs
	//
	//   - event: Verification event details
	//
	// # Outputs
	//
	//   - error: Non-nil if logging failed (should not block verification)
	LogVerificationAttempt(event *VerificationAuditEvent) error
}

type ChainVerificationResult struct {
	Valid             bool   `json:"valid"`
	ChainLength       int    `json:"chain_length"`
	FinalHash         string `json:"final_hash,omitempty"`
	InvalidEventIndex int    `json:"invalid_event_index"`
	ExpectedHash      string `json:"expected_hash,omitempty"`
	ActualHash        string `json:"actual_hash,omitempty"`
	ErrorMessage      string `json:"error_message,omitempty"`
}

type ChainVerifier interface {
	// Verify checks the integrity of a sequence of stream events.
	//
	// # Description
	//
	// Verifies that the hash chain is unbroken and valid.
	//
	// # Inputs
	//
	//   - events: Ordered list of stream events from the session
	//
	// # Outputs
	//
	//   - *ChainVerificationResult: Detailed verification results
	//
	// # Examples
	//
	//   verifier := NewFullChainVerifier(hashComputer)
	//   result := verifier.Verify(events)
	//   if !result.Valid {
	//       log.Warn("chain broken", "error", result.ErrorMessage)
	//   }
	//
	// # Limitations
	//
	//   - Implementation-specific verification depth
	//
	// # Assumptions
	//
	//   - Events are in chronological order
	//   - First event has empty PrevHash
	Verify(events []StreamEvent) *ChainVerificationResult
}

type ChatMode int

type ChatUI interface {
	// Header displays the chat session header with mode and configuration.
	// Deprecated: Use HeaderWithConfig for new code.
	Header(mode ChatMode, pipeline, sessionID string)

	// HeaderWithConfig displays the chat session header with full configuration.
	// This method supports displaying TTL, dataspace, and other metadata.
	HeaderWithConfig(config HeaderConfig)

	// Prompt returns the styled input prompt string
	Prompt() string

	// Response displays the assistant's response
	Response(answer string)

	// Sources displays the sources used in a RAG response
	Sources(sources []SourceInfo)

	// NoSources displays a message when no sources were found
	NoSources()

	// Error displays a chat error message
	Error(err error)

	// SessionResume displays session resume information
	SessionResume(sessionID string, turnCount int)

	// SessionEnd displays session end information
	SessionEnd(sessionID string)

	// SessionEndRich displays rich session end information with stats.
	//
	// This is the "maximalist" session end experience, showing:
	//   - Session ID with copy hint
	//   - Session statistics (messages, tokens, duration)
	//   - Commands for interacting with the session (resume, history)
	//
	// Use this instead of SessionEnd when you have accumulated stats.
	SessionEndRich(sessionID string, stats *SessionStats)

	// ShowAutoCorrection displays a notification that a typo was auto-corrected.
	//
	// # Description
	//
	// Called when a high-confidence typo correction is applied automatically.
	// Informs the user what was corrected so they can undo if needed.
	//
	// # Inputs
	//
	//   - original: The original (misspelled) word
	//   - corrected: The corrected word that will be used
	ShowAutoCorrection(original, corrected string)

	// ShowCorrectionSuggestion displays a suggestion for a possible typo.
	//
	// # Description
	//
	// Called for lower-confidence corrections that require user confirmation.
	// The user can retype their query if the suggestion is correct.
	//
	// # Inputs
	//
	//   - original: The original (possibly misspelled) word
	//   - suggested: The suggested correction
	ShowCorrectionSuggestion(original, suggested string)
}

type DataSpaceStats struct {
	DocumentCount int   `json:"document_count"`  // Actually chunk count
	LastUpdatedAt int64 `json:"last_updated_at"` // Unix ms timestamp
}

type HSMProvider interface {
	// SignWithHSM signs content using an HSM-stored key.
	//
	// # Inputs
	//
	//   - keyLabel: Label of the key in HSM
	//   - content: Content to sign
	//
	// # Outputs
	//
	//   - []byte: Signature bytes
	//   - error: Non-nil if HSM operation failed
	SignWithHSM(keyLabel string, content []byte) ([]byte, error)

	// VerifyWithHSM verifies a signature using HSM.
	//
	// # Inputs
	//
	//   - keyLabel: Label of the public key in HSM
	//   - content: Original content
	//   - signature: Signature to verify
	//
	// # Outputs
	//
	//   - bool: True if signature valid
	//   - error: Non-nil if HSM operation failed
	VerifyWithHSM(keyLabel string, content []byte, signature []byte) (bool, error)
}

type HashComputer interface {
	// ComputeEventHash computes the hash for a stream event.
	//
	// # Description
	//
	// Computes hash using: SHA256(Content || CreatedAt || PrevHash)
	//
	// # Inputs
	//
	//   - content: The event content
	//   - createdAt: Creation timestamp (Unix ms)
	//   - prevHash: Hash of previous event
	//
	// # Outputs
	//
	//   - string: 64-character hex hash
	//
	// # Examples
	//
	//   computer := NewSHA256HashComputer()
	//   hash := computer.ComputeEventHash("Hello", 1735657200000, "abc...")
	//
	// # Limitations
	//
	//   - Hash algorithm is implementation-specific
	//
	// # Assumptions
	//
	//   - Inputs are valid (no nil checks)
	ComputeEventHash(content string, createdAt int64, prevHash string) string

	// ComputeContentHash computes a simple hash of content.
	//
	// # Description
	//
	// Computes SHA256 hash of the provided content string.
	//
	// # Inputs
	//
	//   - content: The content to hash
	//
	// # Outputs
	//
	//   - string: 64-character hex hash
	//
	// # Examples
	//
	//   hash := computer.ComputeContentHash("The answer is 42.")
	//
	// # Limitations
	//
	//   - Empty content produces a valid hash
	//
	// # Assumptions
	//
	//   - Content is valid UTF-8
	ComputeContentHash(content string) string
}

type HeaderConfig struct {
	Mode           ChatMode
	Pipeline       string
	SessionID      string
	TTL            string
	DataSpace      string
	DataSpaceStats *DataSpaceStats // Optional stats from orchestrator
}

type Icon string

type IntegrityInfo struct {
	ChainHash         string            `json:"chain_hash"`
	ContentHash       string            `json:"content_hash"`
	TurnHashes        map[int]string    `json:"turn_hashes,omitempty"`
	SourceHashes      map[string]string `json:"source_hashes,omitempty"`
	ChainLength       int               `json:"chain_length"`
	IntegrityVerified bool              `json:"integrity_verified"`
	VerificationError string            `json:"verification_error,omitempty"`
	VerifiedAt        int64             `json:"verified_at,omitempty"`
}

type KeyedHashComputer interface {
	// ComputeHMAC computes a keyed hash for content.
	//
	// # Inputs
	//
	//   - keyID: Identifier for the key to use (for key rotation)
	//   - content: Content to hash
	//
	// # Outputs
	//
	//   - string: Hex-encoded HMAC
	//   - error: Non-nil if key not found or HSM unavailable
	ComputeHMAC(keyID string, content string) (string, error)

	// VerifyHMAC verifies a keyed hash.
	//
	// # Inputs
	//
	//   - keyID: Identifier for the key used
	//   - content: Original content
	//   - expectedHMAC: HMAC to verify against
	//
	// # Outputs
	//
	//   - bool: True if HMAC matches
	//   - error: Non-nil if verification could not be performed
	VerifyHMAC(keyID string, content string, expectedHMAC string) (bool, error)
}

type Personality struct {
	// Level controls overall verbosity (full, standard, minimal, machine)
	Level PersonalityLevel

	// Theme is the color theme (reserved for future use)
	Theme string

	// ShowTips enables "message in a bottle" style tips
	ShowTips bool

	// NauticalMode enables nautical terminology throughout
	NauticalMode bool
}

type PersonalityLevel string

type ProgressSpinner struct {
	*Spinner
	// contains filtered or unexported fields
}

type PromptOption struct {
	Label       string
	Description string
	Value       string
	Recommended bool
}

type SSEParser interface {
	// ParseLine parses a single line of SSE input.
	//
	// Parameters:
	//   - line: A single line from the SSE stream (without trailing newline)
	//
	// Returns:
	//   - *StreamEvent: The parsed event, or nil for empty/comment lines
	//   - error: Non-nil if JSON parsing failed
	//
	// Line handling:
	//   - Empty lines: Returns nil, nil (event delimiter)
	//   - Comment lines (":"): Returns nil, nil (ignored)
	//   - Data lines ("data: "): Parses JSON payload
	//   - Other lines: Treated as raw token content
	ParseLine(line string) (*StreamEvent, error)

	// ParseRawJSON parses a raw JSON payload into a StreamEvent.
	//
	// Use this when you have JSON without the "data: " prefix.
	// Automatically generates Id and sets CreatedAt.
	//
	// Parameters:
	//   - jsonData: Raw JSON bytes
	//
	// Returns:
	//   - *StreamEvent: The parsed event
	//   - error: Non-nil if JSON parsing failed
	ParseRawJSON(jsonData []byte) (*StreamEvent, error)
}

type SecretAction string

type SecretFinding struct {
	LineNumber  int
	PatternID   string
	PatternName string
	Confidence  string
	Match       string
	Reason      string
}

type SecretPromptOptions struct {
	FilePath      string
	Findings      []SecretFinding
	ShowRedact    bool
	ShowForceSkip bool
}

type SessionStats struct {
	MessageCount         int
	TotalTokens          int
	ThinkingTokens       int
	SourcesUsed          int
	Duration             time.Duration
	FirstResponseLatency time.Duration
	AverageResponseTime  time.Duration
}

type SignatureVerifier interface {
	// VerifySignature verifies a digital signature.
	//
	// # Inputs
	//
	//   - content: Content that was signed
	//   - signature: Base64-encoded signature
	//   - signerID: Identifier for the signer's public key
	//
	// # Outputs
	//
	//   - bool: True if signature is valid
	//   - error: Non-nil if verification could not be performed
	VerifySignature(content string, signature string, signerID string) (bool, error)
}

type SourceInfo struct {
	Id            string  `json:"id,omitempty"`
	CreatedAt     int64   `json:"created_at,omitempty"`
	Source        string  `json:"source"`
	Distance      float64 `json:"distance,omitempty"`
	Score         float64 `json:"score,omitempty"`
	Hash          string  `json:"hash,omitempty"`
	VersionNumber *int    `json:"version_number,omitempty"`
	IsCurrent     *bool   `json:"is_current,omitempty"`
}

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

type SpinnerType int

type StreamCallback func(event StreamEvent) error

type StreamEvent struct {
	// Id is the unique identifier for this event.
	// Generated by the parser or constructor, used for tracing.
	Id string `json:"id"`

	// CreatedAt is the Unix timestamp (milliseconds) when this event was created.
	// This is the local time when the client parsed/created the event.
	CreatedAt int64 `json:"created_at"`

	// Type categorizes this event.
	// This field is always set and determines which other fields are valid.
	Type StreamEventType `json:"type"`

	// Index is the zero-based position of this event in the stream.
	// Set by the StreamReader as events are processed.
	Index int `json:"index"`

	// Content holds token or thinking text.
	// Set when Type is StreamEventToken or StreamEventThinking.
	Content string `json:"content,omitempty"`

	// Message holds status update text.
	// Set when Type is StreamEventStatus.
	Message string `json:"message,omitempty"`

	// Sources holds retrieved knowledge base sources.
	// Set when Type is StreamEventSources.
	Sources []SourceInfo `json:"sources,omitempty"`

	// SessionID holds the conversation session identifier.
	// Set when Type is StreamEventDone.
	SessionID string `json:"session_id,omitempty"`

	// Error holds the error message.
	// Set when Type is StreamEventError.
	Error string `json:"error,omitempty"`

	// RequestID correlates this event with the originating request.
	// May be set by the server or propagated from the request.
	RequestID string `json:"request_id,omitempty"`

	// Hash is the SHA-256 hash of this event for tamper-evident logging.
	// Formula: SHA256(Content || CreatedAt || PrevHash)
	Hash string `json:"hash,omitempty"`

	// PrevHash is the hash of the previous event in the chain.
	// First event has empty PrevHash; subsequent events chain to previous.
	PrevHash string `json:"prev_hash,omitempty"`
}

type StreamEventType string

type StreamReader interface {
	// Read processes a stream, invoking callback for each event.
	//
	// Parameters:
	//   - ctx: Context for cancellation. When cancelled, stops reading.
	//   - r: The source to read from. Caller is responsible for closing.
	//   - callback: Invoked for each parsed event. Return error to stop.
	//
	// Returns:
	//   - error: nil on successful completion, otherwise the error that
	//     stopped reading (context cancellation, parse error, or callback error)
	//
	// The stream is considered complete when:
	//   - EOF is reached
	//   - A terminal event (done/error) is received
	//   - Context is cancelled
	//   - Callback returns an error
	Read(ctx context.Context, r io.Reader, callback StreamCallback) error

	// ReadAll reads the entire stream and returns aggregated result.
	//
	// This is a convenience method that collects all events into a
	// StreamResult. Use Read() when you need real-time event processing.
	//
	// Parameters:
	//   - ctx: Context for cancellation.
	//   - r: The source to read from. Caller is responsible for closing.
	//
	// Returns:
	//   - *StreamResult: Aggregated result with answer, sources, etc.
	//   - error: nil on success, otherwise the error that stopped reading.
	//
	// Note: If the stream ends with an error event, the error is captured
	// in StreamResult.Error and this method returns nil (not an error).
	ReadAll(ctx context.Context, r io.Reader) (*StreamResult, error)
}

type StreamRenderer interface {
	// OnStatus renders a status update (e.g., "Searching...").
	//
	// In interactive mode, may start or update a spinner.
	// In machine mode, prints "STATUS: message".
	//
	// Thread-safe. May be called concurrently with other methods.
	OnStatus(ctx context.Context, message string)

	// OnToken renders a single token from the LLM response.
	//
	// In interactive mode, prints immediately for streaming effect.
	// In machine mode, buffers until Finalize().
	//
	// Tokens should be rendered in order; out-of-order rendering
	// may produce garbled output.
	OnToken(ctx context.Context, token string)

	// OnThinking renders thinking/reasoning tokens (Claude extended thinking).
	//
	// May be styled differently (muted, collapsible) or hidden based on config.
	// In machine mode, buffers until Finalize().
	OnThinking(ctx context.Context, content string)

	// OnSources renders retrieved knowledge base sources inline.
	//
	// Called when sources event arrives (may be before, during, or after tokens).
	// In interactive mode, displays sources immediately for visibility.
	OnSources(ctx context.Context, sources []SourceInfo)

	// OnDone signals stream completion with optional session ID.
	//
	// Stops spinners, flushes buffers, prints final newlines.
	// This is typically the last On* method called (unless OnError).
	OnDone(ctx context.Context, sessionID string)

	// OnError renders an error that occurred during streaming.
	//
	// Stops spinners and displays error message.
	// After OnError, only Finalize() should be called.
	OnError(ctx context.Context, err error)

	// Finalize performs cleanup (stop spinners, flush output).
	//
	// MUST be called when streaming ends, even if abnormally.
	// Safe to call multiple times; subsequent calls are no-ops.
	// Typically called with defer immediately after creating renderer.
	Finalize()

	// Result returns the accumulated result after streaming completes.
	//
	// Contains the full answer, sources, session ID, and metadata.
	// May be called before Finalize() to get partial results.
	Result() *StreamResult
}

type StreamResult struct {
	// Id is the unique identifier for this result.
	Id string `json:"id"`

	// CreatedAt is the Unix timestamp (milliseconds) when streaming began.
	CreatedAt int64 `json:"created_at"`

	// CompletedAt is the Unix timestamp (milliseconds) when streaming ended.
	CompletedAt int64 `json:"completed_at"`

	// RequestID correlates this result with the originating request.
	RequestID string `json:"request_id,omitempty"`

	// Answer is the complete response text (all tokens concatenated).
	Answer string `json:"answer"`

	// Thinking is the complete thinking/reasoning text (Claude extended thinking).
	// May be empty if thinking was not enabled or not generated.
	Thinking string `json:"thinking,omitempty"`

	// Sources is the list of retrieved knowledge base sources.
	// Empty for non-RAG responses.
	Sources []SourceInfo `json:"sources,omitempty"`

	// SessionID is the conversation session identifier.
	// Used for multi-turn conversation continuity.
	SessionID string `json:"session_id,omitempty"`

	// Error is set if the stream ended with an error event.
	// If non-empty, Answer may be incomplete or empty.
	Error string `json:"error,omitempty"`

	// TotalTokens is the number of token events received.
	TotalTokens int `json:"total_tokens"`

	// ThinkingTokens is the number of thinking token events received.
	ThinkingTokens int `json:"thinking_tokens"`

	// TotalEvents is the total number of events received.
	TotalEvents int `json:"total_events"`

	// ModelID identifies which model generated the response.
	ModelID string `json:"model_id,omitempty"`

	// FirstTokenAt is when the first token event arrived (Unix ms).
	FirstTokenAt int64 `json:"first_token_at,omitempty"`

	// ChainHash is the final hash of the event chain.
	// This is the Hash from the last (done/error) event.
	// Used to verify the complete stream integrity.
	ChainHash string `json:"chain_hash,omitempty"`

	// ContentHash is SHA-256 hash of the accumulated answer content.
	// Used for content integrity verification separate from the chain.
	ContentHash string `json:"content_hash,omitempty"`
}

type TimestampAuthority interface {
	// GetTimestamp requests a trusted timestamp for content hash.
	//
	// # Inputs
	//
	//   - contentHash: Hash of content to timestamp
	//
	// # Outputs
	//
	//   - TimestampToken: RFC 3161 timestamp token
	//   - error: Non-nil if TSA unavailable
	GetTimestamp(contentHash string) (*TimestampToken, error)

	// VerifyTimestamp verifies a timestamp token.
	//
	// # Inputs
	//
	//   - token: Previously obtained timestamp token
	//   - contentHash: Hash to verify against
	//
	// # Outputs
	//
	//   - bool: True if timestamp is valid
	//   - error: Non-nil if verification failed
	VerifyTimestamp(token *TimestampToken, contentHash string) (bool, error)
}

type TimestampToken struct {
	// Token is the DER-encoded timestamp token
	Token []byte `json:"token"`

	// Timestamp is the time asserted by the TSA
	Timestamp time.Time `json:"timestamp"`

	// TSAName is the name of the Timestamp Authority
	TSAName string `json:"tsa_name"`

	// SerialNumber is the unique token serial number
	SerialNumber string `json:"serial_number"`
}

type VerificationAuditEvent struct {
	// SessionID being verified
	SessionID string `json:"session_id"`

	// UserID who requested verification (from auth context)
	UserID string `json:"user_id"`

	// TenantID for multi-tenant deployments
	TenantID string `json:"tenant_id"`

	// Timestamp of verification attempt
	Timestamp time.Time `json:"timestamp"`

	// Success indicates if verification passed
	Success bool `json:"success"`

	// FailureReason if verification failed
	FailureReason string `json:"failure_reason,omitempty"`

	// IPAddress of requester
	IPAddress string `json:"ip_address"`

	// RequestID for correlation
	RequestID string `json:"request_id"`
}

type VerificationAuthorizer interface {
	// CanVerify checks if a user can verify a session.
	//
	// # Inputs
	//
	//   - userID: User requesting verification
	//   - sessionID: Session to verify
	//
	// # Outputs
	//
	//   - bool: True if authorized
	//   - error: Non-nil if authorization check failed
	CanVerify(userID string, sessionID string) (bool, error)
}