Type Definitions

/** Paginated API response wrapper */
export interface PaginatedResponse<T> {
  data: T[];
  total: number;
  page: number;
  pageSize: number;
  totalPages: number;
}

/** Standardized API error shape */
export interface ApiError {
  code: string;
  message: string;
  details?: Record<string, unknown>;
  timestamp: string;
}

/** Sort direction for table columns */
export type SortDirection = 'asc' | 'desc';

/** Column-level sort configuration */
export interface SortConfig {
  field: string;
  direction: SortDirection;
}

/** Column-level filter configuration */
export interface FilterConfig {
  field: string;
  operator: 'eq' | 'neq' | 'contains' | 'gt' | 'lt' | 'gte' | 'lte' | 'in';
  value: string | number | boolean | string[];
}

/** Generic key-value metadata record */
export type Metadata = Record<string, string | number | boolean>;

/** All possible session lifecycle states */
export type SessionStatus =
  | 'created'
  | 'running'
  | 'processing'
  | 'pending_approval'
  | 'approved'
  | 'applying'
  | 'completed'
  | 'failed'
  | 'rejected';

/** Orchestration session */
export interface Session {
  id: string;
  skill: string;
  status: SessionStatus;
  created: string;
  updated: string;
  input: SessionInput;
  output: SessionOutput;
  traces: SessionTrace[];
}

/** Input provided when creating a session */
export interface SessionInput {
  files: string[];
  args: Record<string, unknown>;
}

/** Output produced by a completed (or partially completed) session */
export interface SessionOutput {
  artifacts: string[];
  errors: SessionError[];
}

/** Structured error within a session */
export interface SessionError {
  code: string;
  message: string;
  timestamp: string;
}

/** Single trace entry for an agent action within a session */
export interface SessionTrace {
  id: string;
  agentCode: string;
  action: string;
  status: 'started' | 'completed' | 'failed';
  startedAt: string;
  completedAt?: string;
  duration?: number;
  input?: Record<string, unknown>;
  output?: Record<string, unknown>;
  error?: string;
}

/** Operational status of an agent */
export type AgentStatus = 'idle' | 'running' | 'error' | 'disabled';

/** Specialist agent definition */
export interface Agent {
  /** Unique short code (e.g. 'REQ', 'SCH', 'BOM') */
  code: string;

  /** Human-readable name (e.g. 'Requirements Agent') */
  name: string;

  /** Current operational status */
  status: AgentStatus;

  /** Implementation phase: 1 (MVP), 2, or 3 */
  phase: 1 | 2 | 3;

  /** List of hardware disciplines this agent covers */
  disciplines: string[];

  /** Tools available to this agent */
  tools: AgentTool[];

  /** ISO timestamp of last execution, if any */
  lastRun?: string;

  /** Session ID currently being processed, if any */
  currentSession?: string;

  /** Brief description of the agent's capabilities */
  description: string;
}

/** Tool available to an agent */
export interface AgentTool {
  /** Tool display name */
  name: string;

  /** Semantic version */
  version: string;

  /** Whether the tool adapter is currently available */
  available: boolean;

  /** Tool category for grouping */
  category: 'eda' | 'simulation' | 'supply-chain' | 'firmware' | 'document' | 'analysis';
}

/** A file artifact produced by an agent session */
export interface Artifact {
  /** Unique artifact identifier */
  id: string;

  /** Relative path within the workspace (e.g. 'output/bom.csv') */
  path: string;

  /** Artifact type classification */
  type:
    | 'schematic'
    | 'pcb-layout'
    | 'gerber'
    | 'bom'
    | 'firmware'
    | 'report'
    | 'model-3d'
    | 'test-result'
    | 'compliance-evidence'
    | 'other';

  /** Inline content for text-based artifacts (omitted for binary files) */
  content?: string;

  /** SHA-256 hash of the file contents */
  hash: string;

  /** File size in bytes */
  size: number;

  /** ISO timestamp when the artifact was created */
  created: string;

  /** MIME type (e.g. 'application/pdf', 'text/csv') */
  mimeType?: string;
}

/** Component lifecycle status as reported by suppliers */
export type LifecycleStatus = 'active' | 'nrnd' | 'eol' | 'obsolete' | 'unknown';

/** Supply chain risk level for a BOM entry */
export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';

/** Single entry in the bill of materials */
export interface BOMEntry {
  /** Unique BOM line ID */
  id: string;

  /** Reference designator(s) on the schematic (e.g. 'U1', 'R1,R2,R3') */
  designator: string;

  /** Manufacturer part number */
  mpn: string;

  /** Component manufacturer */
  manufacturer: string;

  /** Human-readable description */
  description: string;

  /** Component category (e.g. 'IC', 'Resistor', 'Capacitor', 'Connector') */
  category: string;

  /** Quantity required per unit */
  quantity: number;

  /** Unit price in USD */
  unitPrice: number;

  /** Total price (unitPrice * quantity) */
  totalPrice: number;

  /** Current stock available at preferred distributor */
  stock: number;

  /** Lead time in weeks */
  leadTime: number;

  /** Current lifecycle status */
  lifecycle: LifecycleStatus;

  /** Computed risk level based on lifecycle, stock, lead time, and sourcing */
  risk: RiskLevel;

  /** Alternate components that could replace this part */
  alternates: AlternateComponent[];

  /** Package / footprint (e.g. '0402', 'QFN-48', 'SOT-23') */
  package: string;

  /** Key electrical specifications */
  specifications: Record<string, string | number>;
}

/** An alternate component that can substitute a BOM entry */
export interface AlternateComponent {
  /** Manufacturer part number of the alternate */
  mpn: string;

  /** Alternate manufacturer */
  manufacturer: string;

  /** Unit price in USD */
  unitPrice: number;

  /** Current stock at preferred distributor */
  stock: number;

  /** Lead time in weeks */
  leadTime: number;

  /** Compatibility level with the original part */
  compatibility: 'drop-in' | 'minor-changes' | 'redesign';
}

/** Aggregate BOM risk summary */
export interface BOMRiskSummary {
  /** Overall risk score from 0 (no risk) to 100 (critical) */
  overallScore: number;

  /** Number of components with only a single source */
  singleSourceCount: number;

  /** Number of components at end-of-life */
  eolCount: number;

  /** Number of components marked not-recommended-for-new-designs */
  nrndCount: number;

  /** Number of components with lead time exceeding threshold */
  longLeadCount: number;

  /** BOM entry IDs flagged as high or critical risk */
  highRiskItems: string[];
}

/** Supported compliance markets */
export type ComplianceMarket = 'UKCA' | 'CE' | 'FCC';

/** A single regulatory regime within a market */
export interface ComplianceRegime {
  /** Unique regime ID */
  id: string;

  /** Target market */
  market: ComplianceMarket;

  /** Regime display name (e.g. 'Radio Equipment Directive') */
  name: string;

  /** Reference standard (e.g. 'EN 301 489-1') */
  standard: string;

  /** Brief description of the regime's scope */
  description: string;

  /** Completion progress from 0 to 100 */
  progress: number;

  /** Evidence items required for this regime */
  evidenceItems: EvidenceItem[];

  /** Current status of the regime */
  status: 'not-started' | 'in-progress' | 'submitted' | 'approved' | 'failed';
}

/** A single evidence item required for a compliance regime */
export interface EvidenceItem {
  /** Unique evidence item ID */
  id: string;

  /** Description of what evidence is needed */
  description: string;

  /** Whether this evidence is mandatory */
  required: boolean;

  /** Current status of this evidence item */
  status: 'pending' | 'submitted' | 'approved' | 'rejected';

  /** Artifact ID linking to the submitted evidence, if any */
  artifactId?: string;

  /** Reviewer notes or rejection reason */
  notes?: string;
}

/** Aggregated compliance summary for a market */
export interface ComplianceSummary {
  /** Market being summarized */
  market: ComplianceMarket;

  /** Overall progress percentage across all regimes */
  overallProgress: number;

  /** Individual regime summaries */
  regimes: ComplianceRegime[];

  /** Total number of evidence items across all regimes */
  totalEvidence: number;

  /** Number of evidence items submitted */
  submittedEvidence: number;

  /** Number of evidence items approved */
  approvedEvidence: number;
}

/** Possible node types in the digital thread */
export type NodeType =
  | 'requirement'
  | 'design'
  | 'component'
  | 'test'
  | 'evidence'
  | 'certification'
  | 'risk'
  | 'decision';

/** A single node in the digital thread graph */
export interface DigitalThreadNode {
  /** Unique node identifier */
  id: string;

  /** Semantic type of this node */
  type: NodeType;

  /** Display label */
  label: string;

  /** Arbitrary properties specific to the node type */
  properties: Record<string, unknown>;

  /** Optional status indicator */
  status?: 'active' | 'draft' | 'approved' | 'deprecated' | 'blocked';
}

/** An edge connecting two nodes in the digital thread */
export interface DigitalThreadEdge {
  /** Unique edge identifier */
  id: string;

  /** Source node ID */
  source: string;

  /** Target node ID */
  target: string;

  /** Semantic relationship type */
  relationship:
    | 'traces-to'
    | 'verified-by'
    | 'implemented-by'
    | 'depends-on'
    | 'mitigated-by'
    | 'approved-in'
    | 'derived-from';

  /** Optional edge metadata */
  properties?: Record<string, unknown>;
}

/** Complete digital thread graph structure */
export interface DigitalThreadGraph {
  /** All nodes in the graph */
  nodes: DigitalThreadNode[];

  /** All edges connecting the nodes */
  edges: DigitalThreadEdge[];
}

/** A supply chain risk entry */
export interface SupplyChainRisk {
  /** Unique risk identifier */
  id: string;

  /** Risk category */
  type: 'single-source' | 'eol' | 'long-lead' | 'price-volatility' | 'geopolitical' | 'quality';

  /** Severity level */
  severity: 'low' | 'medium' | 'high' | 'critical';

  /** Affected component reference designator */
  component: string;

  /** Manufacturer part number */
  mpn: string;

  /** Human-readable risk description */
  description: string;

  /** Suggested mitigation action, if available */
  mitigation?: string;
}

/** End-of-life warning for a component */
export interface EOLWarning {
  /** Manufacturer part number */
  mpn: string;

  /** Component manufacturer */
  manufacturer: string;

  /** Current lifecycle status */
  currentStatus: 'active' | 'nrnd' | 'eol' | 'obsolete';

  /** Estimated end-of-life date, if known */
  estimatedEOL?: string;

  /** Reference designators in the current design using this part */
  affectedDesignators: string[];

  /** Number of known alternate components */
  alternateCount: number;
}

/** Historical price data for a component */
export interface PriceHistory {
  /** Manufacturer part number */
  mpn: string;

  /** Time-series data points */
  dataPoints: PriceDataPoint[];
}

/** Single price data point */
export interface PriceDataPoint {
  /** ISO date string */
  date: string;

  /** Unit price in USD */
  price: number;

  /** Distributor reporting this price */
  distributor: string;
}

/** Current stock level at a distributor */
export interface StockLevel {
  /** Manufacturer part number */
  mpn: string;

  /** Distributor name */
  distributor: string;

  /** Current stock quantity */
  stock: number;

  /** Lead time in weeks */
  leadTime: number;

  /** Minimum order quantity */
  moq: number;

  /** ISO timestamp of last data update */
  lastUpdated: string;
}

/** Approval decision status */
export type ApprovalStatus = 'pending' | 'approved' | 'rejected';

/** An approval request for a session's proposed changes */
export interface Approval {
  /** Unique approval identifier */
  id: string;

  /** Session that generated this approval request */
  sessionId: string;

  /** Type of approval (e.g. 'design-change', 'bom-update', 'compliance-submission') */
  type: string;

  /** Short title summarizing the approval */
  title: string;

  /** Detailed description of what is being approved */
  description: string;

  /** Current approval status */
  status: ApprovalStatus;

  /** Agent or user who requested the approval */
  requestedBy: string;

  /** ISO timestamp when the approval was requested */
  requestedAt: string;

  /** ISO timestamp when the approval was resolved, if any */
  resolvedAt?: string;

  /** User who resolved the approval, if any */
  resolvedBy?: string;

  /** List of file changes included in this approval */
  changes: ApprovalChange[];

  /** Discussion thread on this approval */
  comments: ApprovalComment[];
}

/** A single file change within an approval request */
export interface ApprovalChange {
  /** File path relative to workspace root */
  file: string;

  /** Type of change */
  type: 'add' | 'modify' | 'delete';

  /** Unified diff string, if available */
  diff?: string;
}

/** A comment on an approval request */
export interface ApprovalComment {
  /** Unique comment identifier */
  id: string;

  /** Author of the comment (user or agent code) */
  author: string;

  /** Comment content (Markdown supported) */
  content: string;

  /** ISO timestamp when the comment was posted */
  timestamp: string;
}

/** Component health status */
export type ComponentHealth = 'healthy' | 'degraded' | 'unhealthy';

/** Response from GET /api/v1/health */
export interface HealthResponse {
  /** Overall system status */
  status: ComponentHealth;

  /** Platform version string */
  version: string;

  /** Uptime in seconds */
  uptime: number;

  /** Individual component health statuses */
  components: {
    gateway: ComponentHealth;
    llm_provider: ComponentHealth;
    neo4j: ComponentHealth;
    minio: ComponentHealth;
    tools: Record<string, ComponentHealth>;
  };
}

/** Response from GET /api/v1/status */
export interface StatusResponse {
  /** Platform version string */
  version: string;

  /** Current workspace path */
  workspace: string;

  /** Session count breakdown */
  sessions: {
    active: number;
    completed: number;
    failed: number;
    total: number;
  };

  /** List of registered tool adapter names */
  tools: string[];

  /** List of registered agent codes */
  agents: string[];
}

/** All possible WebSocket event types */
export type WebSocketEventType =
  | 'session.started'
  | 'session.progress'
  | 'session.complete'
  | 'session.failed'
  | 'agent.status'
  | 'bom.updated'
  | 'compliance.updated'
  | 'test.completed'
  | 'approval.requested'
  | 'approval.resolved'
  | 'health.changed';

/** Base WebSocket message envelope */
export interface WebSocketMessage<T = unknown> {
  /** Event type identifier */
  event: WebSocketEventType;

  /** Event-specific payload */
  data: T;

  /** ISO timestamp when the event was emitted */
  timestamp: string;
}

/** Payload for session.started events */
export interface SessionStartedEvent {
  sessionId: string;
  skill: string;
}

/** Payload for session.progress / agent.status events */
export interface AgentProgressEvent {
  sessionId: string;
  agentCode: string;
  action: string;
  progress: number;
  message?: string;
}

/** Payload for session.complete events */
export interface SessionCompleteEvent {
  sessionId: string;
  status: 'completed' | 'failed' | 'rejected';
  artifacts: string[];
  errors?: string[];
}

/** Payload for bom.updated events */
export interface BOMUpdatedEvent {
  sessionId: string;
  entriesChanged: number;
  riskScore: number;
}

/** Payload for test.completed events */
export interface TestCompletedEvent {
  sessionId: string;
  testId: string;
  status: 'passed' | 'failed' | 'skipped';
  duration: number;
}

/** Manufacturing gate type */
export type GateType = 'EVT' | 'DVT' | 'PVT';

/** Readiness assessment for a manufacturing gate */
export interface GateReadiness {
  /** Which gate this assessment is for */
  gate: GateType;

  /** Overall readiness score from 0 to 100 */
  score: number;

  /** Percentage of required evidence artifacts submitted */
  evidenceCompleteness: number;

  /** Whether all critical defects have been resolved */
  criticalDefectsResolved: boolean;

  /** Percentage of requirements with traceability to test results */
  requirementsCoverage: number;

  /** List of blocking issues preventing gate passage */
  blockers: GateBlocker[];

  /** Gate status */
  status: 'not-ready' | 'at-risk' | 'ready' | 'passed';
}

/** A single blocker preventing gate passage */
export interface GateBlocker {
  /** Blocker identifier */
  id: string;

  /** Short description of the blocking issue */
  title: string;

  /** Severity of the blocker */
  severity: 'minor' | 'major' | 'critical';

  /** Owner responsible for resolution */
  owner?: string;

  /** Target resolution date */
  dueDate?: string;
}

/** Status of a test case */
export type TestStatus = 'pending' | 'running' | 'passed' | 'failed' | 'skipped' | 'blocked';

/** A test case definition */
export interface TestCase {
  /** Unique test case identifier */
  id: string;

  /** Test case name */
  name: string;

  /** Test category (e.g. 'functional', 'environmental', 'emc', 'safety', 'reliability') */
  category: string;

  /** Requirement ID this test traces to */
  requirementId: string;

  /** Current test status */
  status: TestStatus;

  /** ISO timestamp of last execution, if any */
  lastRun?: string;

  /** Most recent test result, if any */
  results?: TestResult[];
}

/** Result of a single test execution */
export interface TestResult {
  /** Unique run identifier */
  runId: string;

  /** ISO timestamp of the test run */
  timestamp: string;

  /** Outcome of the run */
  status: 'passed' | 'failed' | 'skipped';

  /** Duration in milliseconds */
  duration: number;

  /** Additional notes or failure details */
  notes?: string;
}

/** Test coverage summary */
export interface TestCoverage {
  /** Total number of test cases */
  total: number;

  /** Number of test cases with at least one passing result */
  covered: number;

  /** Coverage percentage (covered / total * 100) */
  percentage: number;

  /** Coverage broken down by test category */
  byCategory: CategoryCoverage[];
}

/** Coverage for a single test category */
export interface CategoryCoverage {
  /** Category name */
  category: string;

  /** Total tests in this category */
  total: number;

  /** Tests with passing results in this category */
  covered: number;

  /** Category-level coverage percentage */
  percentage: number;
}

/** FMEA (Failure Mode and Effects Analysis) entry */
export interface FMEAEntry {
  /** Unique FMEA entry identifier */
  id: string;

  /** Component or subsystem being analyzed */
  component: string;

  /** Description of the potential failure mode */
  failureMode: string;

  /** Effect of the failure on the system */
  effect: string;

  /** Root cause of the failure mode */
  cause: string;

  /** Severity rating from 1 (negligible) to 10 (hazardous) */
  severity: number;

  /** Occurrence rating from 1 (unlikely) to 10 (almost certain) */
  occurrence: number;

  /** Detection rating from 1 (almost certain detection) to 10 (undetectable) */
  detection: number;

  /** Risk Priority Number (severity * occurrence * detection) */
  rpn: number;

  /** Recommended corrective action */
  action: string;

  /** Current status of the corrective action */
  status: 'open' | 'in-progress' | 'resolved' | 'accepted';
}