feat(sdk,iace): add Personalized Drafting Pipeline v2 and IACE engine

Drafting Engine: 7-module pipeline with narrative tags, allowed facts governance,
PII sanitizer, prose validator with repair loop, hash-based cache, and terminology
guide. v1 fallback via ?v=1 query param.

IACE: Initial AI-Act Conformity Engine with risk classifier, completeness checker,
hazard library, and PostgreSQL store for AI system assessments.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ai-compliance-sdk/internal/iace/models.go

@@ -0,0 +1,485 @@
+package iace
+
+import (
+	"encoding/json"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// ============================================================================
+// Constants / Enums
+// ============================================================================
+
+// ProjectStatus represents the lifecycle status of an IACE project
+type ProjectStatus string
+
+const (
+	ProjectStatusDraft          ProjectStatus = "draft"
+	ProjectStatusOnboarding     ProjectStatus = "onboarding"
+	ProjectStatusClassification ProjectStatus = "classification"
+	ProjectStatusHazardAnalysis ProjectStatus = "hazard_analysis"
+	ProjectStatusMitigation     ProjectStatus = "mitigation"
+	ProjectStatusVerification   ProjectStatus = "verification"
+	ProjectStatusTechFile       ProjectStatus = "tech_file"
+	ProjectStatusCompleted      ProjectStatus = "completed"
+	ProjectStatusArchived       ProjectStatus = "archived"
+)
+
+// ComponentType represents the type of a system component
+type ComponentType string
+
+const (
+	ComponentTypeSoftware   ComponentType = "software"
+	ComponentTypeFirmware   ComponentType = "firmware"
+	ComponentTypeAIModel    ComponentType = "ai_model"
+	ComponentTypeHMI        ComponentType = "hmi"
+	ComponentTypeSensor     ComponentType = "sensor"
+	ComponentTypeActuator   ComponentType = "actuator"
+	ComponentTypeController ComponentType = "controller"
+	ComponentTypeNetwork    ComponentType = "network"
+	ComponentTypeOther      ComponentType = "other"
+)
+
+// RegulationType represents the applicable EU regulation
+type RegulationType string
+
+const (
+	RegulationNIS2                RegulationType = "nis2"
+	RegulationAIAct               RegulationType = "ai_act"
+	RegulationCRA                 RegulationType = "cra"
+	RegulationMachineryRegulation RegulationType = "machinery_regulation"
+)
+
+// HazardStatus represents the lifecycle status of a hazard
+type HazardStatus string
+
+const (
+	HazardStatusIdentified HazardStatus = "identified"
+	HazardStatusAssessed   HazardStatus = "assessed"
+	HazardStatusMitigated  HazardStatus = "mitigated"
+	HazardStatusAccepted   HazardStatus = "accepted"
+	HazardStatusClosed     HazardStatus = "closed"
+)
+
+// AssessmentType represents the type of risk assessment
+type AssessmentType string
+
+const (
+	AssessmentTypeInitial        AssessmentType = "initial"
+	AssessmentTypePostMitigation AssessmentType = "post_mitigation"
+	AssessmentTypeReassessment   AssessmentType = "reassessment"
+)
+
+// RiskLevel represents the severity level of a risk
+type RiskLevel string
+
+const (
+	RiskLevelCritical   RiskLevel = "critical"
+	RiskLevelHigh       RiskLevel = "high"
+	RiskLevelMedium     RiskLevel = "medium"
+	RiskLevelLow        RiskLevel = "low"
+	RiskLevelNegligible RiskLevel = "negligible"
+)
+
+// ReductionType represents the type of risk reduction measure
+type ReductionType string
+
+const (
+	ReductionTypeDesign      ReductionType = "design"
+	ReductionTypeProtective  ReductionType = "protective"
+	ReductionTypeInformation ReductionType = "information"
+)
+
+// MitigationStatus represents the lifecycle status of a mitigation measure
+type MitigationStatus string
+
+const (
+	MitigationStatusPlanned     MitigationStatus = "planned"
+	MitigationStatusImplemented MitigationStatus = "implemented"
+	MitigationStatusVerified    MitigationStatus = "verified"
+	MitigationStatusRejected    MitigationStatus = "rejected"
+)
+
+// VerificationMethod represents the method used for verification
+type VerificationMethod string
+
+const (
+	VerificationMethodTest       VerificationMethod = "test"
+	VerificationMethodAnalysis   VerificationMethod = "analysis"
+	VerificationMethodInspection VerificationMethod = "inspection"
+	VerificationMethodReview     VerificationMethod = "review"
+)
+
+// TechFileSectionStatus represents the status of a technical file section
+type TechFileSectionStatus string
+
+const (
+	TechFileSectionStatusDraft     TechFileSectionStatus = "draft"
+	TechFileSectionStatusGenerated TechFileSectionStatus = "generated"
+	TechFileSectionStatusReviewed  TechFileSectionStatus = "reviewed"
+	TechFileSectionStatusApproved  TechFileSectionStatus = "approved"
+)
+
+// MonitoringEventType represents the type of monitoring event
+type MonitoringEventType string
+
+const (
+	MonitoringEventTypeIncident        MonitoringEventType = "incident"
+	MonitoringEventTypeUpdate          MonitoringEventType = "update"
+	MonitoringEventTypeDriftAlert      MonitoringEventType = "drift_alert"
+	MonitoringEventTypeRegulationChange MonitoringEventType = "regulation_change"
+	MonitoringEventTypeAudit           MonitoringEventType = "audit"
+)
+
+// AuditAction represents the type of action recorded in the audit trail
+type AuditAction string
+
+const (
+	AuditActionCreate  AuditAction = "create"
+	AuditActionUpdate  AuditAction = "update"
+	AuditActionDelete  AuditAction = "delete"
+	AuditActionApprove AuditAction = "approve"
+	AuditActionVerify  AuditAction = "verify"
+)
+
+// ============================================================================
+// Main Entities
+// ============================================================================
+
+// Project represents an IACE compliance project for a machine or system
+type Project struct {
+	ID                   uuid.UUID        `json:"id"`
+	TenantID             uuid.UUID        `json:"tenant_id"`
+	MachineName          string           `json:"machine_name"`
+	MachineType          string           `json:"machine_type"`
+	Manufacturer         string           `json:"manufacturer"`
+	Description          string           `json:"description,omitempty"`
+	NarrativeText        string           `json:"narrative_text,omitempty"`
+	Status               ProjectStatus    `json:"status"`
+	CEMarkingTarget      string           `json:"ce_marking_target,omitempty"`
+	CompletenessScore    float64          `json:"completeness_score"`
+	RiskSummary          map[string]int   `json:"risk_summary,omitempty"`
+	TriggeredRegulations json.RawMessage  `json:"triggered_regulations,omitempty"`
+	Metadata             json.RawMessage  `json:"metadata,omitempty"`
+	CreatedAt            time.Time        `json:"created_at"`
+	UpdatedAt            time.Time        `json:"updated_at"`
+	ArchivedAt           *time.Time       `json:"archived_at,omitempty"`
+}
+
+// Component represents a system component within a project
+type Component struct {
+	ID                uuid.UUID       `json:"id"`
+	ProjectID         uuid.UUID       `json:"project_id"`
+	ParentID          *uuid.UUID      `json:"parent_id,omitempty"`
+	Name              string          `json:"name"`
+	ComponentType     ComponentType   `json:"component_type"`
+	Version           string          `json:"version,omitempty"`
+	Description       string          `json:"description,omitempty"`
+	IsSafetyRelevant  bool            `json:"is_safety_relevant"`
+	IsNetworked       bool            `json:"is_networked"`
+	Metadata          json.RawMessage `json:"metadata,omitempty"`
+	SortOrder         int             `json:"sort_order"`
+	CreatedAt         time.Time       `json:"created_at"`
+	UpdatedAt         time.Time       `json:"updated_at"`
+}
+
+// RegulatoryClassification represents the classification result for a regulation
+type RegulatoryClassification struct {
+	ID                   uuid.UUID       `json:"id"`
+	ProjectID            uuid.UUID       `json:"project_id"`
+	Regulation           RegulationType  `json:"regulation"`
+	ClassificationResult string          `json:"classification_result"`
+	RiskLevel            RiskLevel       `json:"risk_level"`
+	Confidence           float64         `json:"confidence"`
+	Reasoning            string          `json:"reasoning,omitempty"`
+	RAGSources           json.RawMessage `json:"rag_sources,omitempty"`
+	Requirements         json.RawMessage `json:"requirements,omitempty"`
+	CreatedAt            time.Time       `json:"created_at"`
+	UpdatedAt            time.Time       `json:"updated_at"`
+}
+
+// HazardLibraryEntry represents a reusable hazard template from the library
+type HazardLibraryEntry struct {
+	ID                       uuid.UUID       `json:"id"`
+	Category                 string          `json:"category"`
+	Name                     string          `json:"name"`
+	Description              string          `json:"description,omitempty"`
+	DefaultSeverity          int             `json:"default_severity"`
+	DefaultProbability       int             `json:"default_probability"`
+	ApplicableComponentTypes []string        `json:"applicable_component_types"`
+	RegulationReferences     []string        `json:"regulation_references"`
+	SuggestedMitigations     json.RawMessage `json:"suggested_mitigations,omitempty"`
+	IsBuiltin                bool            `json:"is_builtin"`
+	TenantID                 *uuid.UUID      `json:"tenant_id,omitempty"`
+	CreatedAt                time.Time       `json:"created_at"`
+}
+
+// Hazard represents a specific hazard identified within a project
+type Hazard struct {
+	ID              uuid.UUID    `json:"id"`
+	ProjectID       uuid.UUID    `json:"project_id"`
+	ComponentID     uuid.UUID    `json:"component_id"`
+	LibraryHazardID *uuid.UUID   `json:"library_hazard_id,omitempty"`
+	Name            string       `json:"name"`
+	Description     string       `json:"description,omitempty"`
+	Scenario        string       `json:"scenario,omitempty"`
+	Category        string       `json:"category"`
+	Status          HazardStatus `json:"status"`
+	CreatedAt       time.Time    `json:"created_at"`
+	UpdatedAt       time.Time    `json:"updated_at"`
+}
+
+// RiskAssessment represents a quantitative risk assessment for a hazard
+type RiskAssessment struct {
+	ID                      uuid.UUID      `json:"id"`
+	HazardID                uuid.UUID      `json:"hazard_id"`
+	Version                 int            `json:"version"`
+	AssessmentType          AssessmentType `json:"assessment_type"`
+	Severity                int            `json:"severity"`
+	Exposure                int            `json:"exposure"`
+	Probability             int            `json:"probability"`
+	InherentRisk            float64        `json:"inherent_risk"`
+	ControlMaturity         int            `json:"control_maturity"`
+	ControlCoverage         float64        `json:"control_coverage"`
+	TestEvidenceStrength    float64        `json:"test_evidence_strength"`
+	CEff                    float64        `json:"c_eff"`
+	ResidualRisk            float64        `json:"residual_risk"`
+	RiskLevel               RiskLevel      `json:"risk_level"`
+	IsAcceptable            bool           `json:"is_acceptable"`
+	AcceptanceJustification string         `json:"acceptance_justification,omitempty"`
+	AssessedBy              uuid.UUID      `json:"assessed_by"`
+	CreatedAt               time.Time      `json:"created_at"`
+}
+
+// Mitigation represents a risk reduction measure applied to a hazard
+type Mitigation struct {
+	ID                 uuid.UUID          `json:"id"`
+	HazardID           uuid.UUID          `json:"hazard_id"`
+	ReductionType      ReductionType      `json:"reduction_type"`
+	Name               string             `json:"name"`
+	Description        string             `json:"description,omitempty"`
+	Status             MitigationStatus   `json:"status"`
+	VerificationMethod VerificationMethod `json:"verification_method,omitempty"`
+	VerificationResult string             `json:"verification_result,omitempty"`
+	VerifiedAt         *time.Time         `json:"verified_at,omitempty"`
+	VerifiedBy         uuid.UUID          `json:"verified_by,omitempty"`
+	CreatedAt          time.Time          `json:"created_at"`
+	UpdatedAt          time.Time          `json:"updated_at"`
+}
+
+// Evidence represents an uploaded file that serves as evidence for compliance
+type Evidence struct {
+	ID                 uuid.UUID  `json:"id"`
+	ProjectID          uuid.UUID  `json:"project_id"`
+	MitigationID       *uuid.UUID `json:"mitigation_id,omitempty"`
+	VerificationPlanID *uuid.UUID `json:"verification_plan_id,omitempty"`
+	FileName           string     `json:"file_name"`
+	FilePath           string     `json:"file_path"`
+	FileHash           string     `json:"file_hash"`
+	FileSize           int64      `json:"file_size"`
+	MimeType           string     `json:"mime_type"`
+	Description        string     `json:"description,omitempty"`
+	UploadedBy         uuid.UUID  `json:"uploaded_by"`
+	CreatedAt          time.Time  `json:"created_at"`
+}
+
+// VerificationPlan represents a plan for verifying compliance measures
+type VerificationPlan struct {
+	ID                 uuid.UUID          `json:"id"`
+	ProjectID          uuid.UUID          `json:"project_id"`
+	HazardID           *uuid.UUID         `json:"hazard_id,omitempty"`
+	MitigationID       *uuid.UUID         `json:"mitigation_id,omitempty"`
+	Title              string             `json:"title"`
+	Description        string             `json:"description,omitempty"`
+	AcceptanceCriteria string             `json:"acceptance_criteria,omitempty"`
+	Method             VerificationMethod `json:"method"`
+	Status             string             `json:"status"`
+	Result             string             `json:"result,omitempty"`
+	CompletedAt        *time.Time         `json:"completed_at,omitempty"`
+	CompletedBy        uuid.UUID          `json:"completed_by,omitempty"`
+	CreatedAt          time.Time          `json:"created_at"`
+	UpdatedAt          time.Time          `json:"updated_at"`
+}
+
+// TechFileSection represents a section of the technical documentation file
+type TechFileSection struct {
+	ID          uuid.UUID             `json:"id"`
+	ProjectID   uuid.UUID             `json:"project_id"`
+	SectionType string                `json:"section_type"`
+	Title       string                `json:"title"`
+	Content     string                `json:"content,omitempty"`
+	Version     int                   `json:"version"`
+	Status      TechFileSectionStatus `json:"status"`
+	ApprovedBy  uuid.UUID             `json:"approved_by,omitempty"`
+	ApprovedAt  *time.Time            `json:"approved_at,omitempty"`
+	Metadata    json.RawMessage       `json:"metadata,omitempty"`
+	CreatedAt   time.Time             `json:"created_at"`
+	UpdatedAt   time.Time             `json:"updated_at"`
+}
+
+// MonitoringEvent represents a post-market monitoring event
+type MonitoringEvent struct {
+	ID               uuid.UUID           `json:"id"`
+	ProjectID        uuid.UUID           `json:"project_id"`
+	EventType        MonitoringEventType `json:"event_type"`
+	Title            string              `json:"title"`
+	Description      string              `json:"description,omitempty"`
+	Severity         string              `json:"severity"`
+	ImpactAssessment string              `json:"impact_assessment,omitempty"`
+	Status           string              `json:"status"`
+	ResolvedAt       *time.Time          `json:"resolved_at,omitempty"`
+	ResolvedBy       uuid.UUID           `json:"resolved_by,omitempty"`
+	Metadata         json.RawMessage     `json:"metadata,omitempty"`
+	CreatedAt        time.Time           `json:"created_at"`
+	UpdatedAt        time.Time           `json:"updated_at"`
+}
+
+// AuditTrailEntry represents an immutable audit log entry for compliance traceability
+type AuditTrailEntry struct {
+	ID         uuid.UUID       `json:"id"`
+	ProjectID  uuid.UUID       `json:"project_id"`
+	EntityType string          `json:"entity_type"`
+	EntityID   uuid.UUID       `json:"entity_id"`
+	Action     AuditAction     `json:"action"`
+	UserID     uuid.UUID       `json:"user_id"`
+	OldValues  json.RawMessage `json:"old_values,omitempty"`
+	NewValues  json.RawMessage `json:"new_values,omitempty"`
+	Hash       string          `json:"hash"`
+	CreatedAt  time.Time       `json:"created_at"`
+}
+
+// ============================================================================
+// API Request Types
+// ============================================================================
+
+// CreateProjectRequest is the API request for creating a new IACE project
+type CreateProjectRequest struct {
+	MachineName     string          `json:"machine_name" binding:"required"`
+	MachineType     string          `json:"machine_type" binding:"required"`
+	Manufacturer    string          `json:"manufacturer" binding:"required"`
+	Description     string          `json:"description,omitempty"`
+	NarrativeText   string          `json:"narrative_text,omitempty"`
+	CEMarkingTarget string          `json:"ce_marking_target,omitempty"`
+	Metadata        json.RawMessage `json:"metadata,omitempty"`
+}
+
+// UpdateProjectRequest is the API request for updating an existing project
+type UpdateProjectRequest struct {
+	MachineName     *string          `json:"machine_name,omitempty"`
+	MachineType     *string          `json:"machine_type,omitempty"`
+	Manufacturer    *string          `json:"manufacturer,omitempty"`
+	Description     *string          `json:"description,omitempty"`
+	NarrativeText   *string          `json:"narrative_text,omitempty"`
+	CEMarkingTarget *string          `json:"ce_marking_target,omitempty"`
+	Metadata        *json.RawMessage `json:"metadata,omitempty"`
+}
+
+// CreateComponentRequest is the API request for adding a component to a project
+type CreateComponentRequest struct {
+	ProjectID        uuid.UUID     `json:"project_id" binding:"required"`
+	ParentID         *uuid.UUID    `json:"parent_id,omitempty"`
+	Name             string        `json:"name" binding:"required"`
+	ComponentType    ComponentType `json:"component_type" binding:"required"`
+	Version          string        `json:"version,omitempty"`
+	Description      string        `json:"description,omitempty"`
+	IsSafetyRelevant bool          `json:"is_safety_relevant"`
+	IsNetworked      bool          `json:"is_networked"`
+}
+
+// CreateHazardRequest is the API request for creating a new hazard
+type CreateHazardRequest struct {
+	ProjectID       uuid.UUID  `json:"project_id" binding:"required"`
+	ComponentID     uuid.UUID  `json:"component_id" binding:"required"`
+	LibraryHazardID *uuid.UUID `json:"library_hazard_id,omitempty"`
+	Name            string     `json:"name" binding:"required"`
+	Description     string     `json:"description,omitempty"`
+	Scenario        string     `json:"scenario,omitempty"`
+	Category        string     `json:"category" binding:"required"`
+}
+
+// AssessRiskRequest is the API request for performing a risk assessment
+type AssessRiskRequest struct {
+	HazardID                uuid.UUID `json:"hazard_id" binding:"required"`
+	Severity                int       `json:"severity" binding:"required"`
+	Exposure                int       `json:"exposure" binding:"required"`
+	Probability             int       `json:"probability" binding:"required"`
+	ControlMaturity         int       `json:"control_maturity" binding:"required"`
+	ControlCoverage         float64   `json:"control_coverage" binding:"required"`
+	TestEvidenceStrength    float64   `json:"test_evidence_strength" binding:"required"`
+	AcceptanceJustification string    `json:"acceptance_justification,omitempty"`
+}
+
+// CreateMitigationRequest is the API request for creating a mitigation measure
+type CreateMitigationRequest struct {
+	HazardID      uuid.UUID     `json:"hazard_id" binding:"required"`
+	ReductionType ReductionType `json:"reduction_type" binding:"required"`
+	Name          string        `json:"name" binding:"required"`
+	Description   string        `json:"description,omitempty"`
+}
+
+// CreateVerificationPlanRequest is the API request for creating a verification plan
+type CreateVerificationPlanRequest struct {
+	ProjectID          uuid.UUID          `json:"project_id" binding:"required"`
+	HazardID           *uuid.UUID         `json:"hazard_id,omitempty"`
+	MitigationID       *uuid.UUID         `json:"mitigation_id,omitempty"`
+	Title              string             `json:"title" binding:"required"`
+	Description        string             `json:"description,omitempty"`
+	AcceptanceCriteria string             `json:"acceptance_criteria,omitempty"`
+	Method             VerificationMethod `json:"method" binding:"required"`
+}
+
+// CreateMonitoringEventRequest is the API request for logging a monitoring event
+type CreateMonitoringEventRequest struct {
+	ProjectID   uuid.UUID           `json:"project_id" binding:"required"`
+	EventType   MonitoringEventType `json:"event_type" binding:"required"`
+	Title       string              `json:"title" binding:"required"`
+	Description string              `json:"description,omitempty"`
+	Severity    string              `json:"severity" binding:"required"`
+}
+
+// InitFromProfileRequest is the API request for initializing a project from a company profile
+type InitFromProfileRequest struct {
+	CompanyProfile  json.RawMessage `json:"company_profile" binding:"required"`
+	ComplianceScope json.RawMessage `json:"compliance_scope" binding:"required"`
+}
+
+// ============================================================================
+// API Response Types
+// ============================================================================
+
+// ProjectListResponse is the API response for listing projects
+type ProjectListResponse struct {
+	Projects []Project `json:"projects"`
+	Total    int       `json:"total"`
+}
+
+// ProjectDetailResponse is the API response for a single project with related entities
+type ProjectDetailResponse struct {
+	Project
+	Components      []Component               `json:"components"`
+	Classifications []RegulatoryClassification `json:"classifications"`
+	CompletenessGates []CompletenessGate       `json:"completeness_gates"`
+}
+
+// RiskSummaryResponse is the API response for an aggregated risk overview
+type RiskSummaryResponse struct {
+	TotalHazards     int       `json:"total_hazards"`
+	Critical         int       `json:"critical"`
+	High             int       `json:"high"`
+	Medium           int       `json:"medium"`
+	Low              int       `json:"low"`
+	Negligible       int       `json:"negligible"`
+	OverallRiskLevel RiskLevel `json:"overall_risk_level"`
+	AllAcceptable    bool      `json:"all_acceptable"`
+}
+
+// CompletenessGate represents a single gate in the project completeness checklist
+type CompletenessGate struct {
+	ID       string `json:"id"`
+	Category string `json:"category"`
+	Label    string `json:"label"`
+	Required bool   `json:"required"`
+	Passed   bool   `json:"passed"`
+	Details  string `json:"details,omitempty"`
+}