feat: implement M2 contracts (issues 5, 6, 7, 8)

README.md

@@ -15,7 +15,7 @@ Before adopting `catnet-core`, please review our [API Stability Policy](docs/con
 | `pkg/targets` | `ParseRange` | Target parsing and CIDR utilities. |
 | `pkg/discovery` | `Ping`, `ReverseDNS`, `GetMAC` | Host liveness and resolution primitives. |
 | `pkg/ports` | `ScanPorts` | Port scanning utilities. |
-| `pkg/exporter` | `ExportJSON`, `ExportXML`, `ExportCSV` | Safe result export functions (with CSV injection prevention). |
+| `pkg/exporter` | `ExportJSON`, `ExportXML`, `ExportCSV` | Safe result export functions. JSON is the canonical schema reference format. |
 | `pkg/scanner` | *Deprecated* | Temporary compatibility wrapper. Do not use for new code. |
 
 ## Quickstart
@@ -39,16 +39,25 @@ func main() {
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 
-	err := engine.StartScan(ctx, ips, cfg, func(d results.DeviceInfo) {
-		if d.IsAlive {
-			fmt.Printf("Found: %s (%s)\n", d.IP, d.MAC)
+	report, err := engine.StartScan(ctx, ips, cfg, func(event engine.ScanEvent) {
+		switch event.Type {
+		case engine.EventResult:
+			if event.Device != nil && event.Device.IsAlive {
+				fmt.Printf("Found: %s (%s)\n", event.Device.IP, event.Device.MAC)
+			}
+		case engine.EventProgress:
+			fmt.Printf("Progress: %.2f%%\n", event.Progress*100)
+		case engine.EventLifecycleStart:
+			fmt.Println("Scan started...")
+		case engine.EventLifecycleComplete:
+			fmt.Println("Scan completed!")
 		}
-	}, func(progress float64) {
-		fmt.Printf("Progress: %.2f%%\n", progress*100)
 	})
 
 	if err != nil {
 		fmt.Printf("Scan failed: %v\n", err)
+	} else {
+		fmt.Printf("Total Scanned: %d, Alive: %d\n", report.Total, report.Alive)
 	}
 }
 ```

docs/contracts/events.md

@@ -0,0 +1,37 @@
+# Scan Lifecycle Events
+
+The `catnet-core` engine exposes a stream of typed events during scan execution to allow consumers (CLI, TUI, GUI) to react to progress and lifecycle changes without coupling to internal logic.
+
+## Event Signature
+
+Events are dispatched synchronously via the `engine.EventCallback` function:
+```go
+type EventCallback func(event ScanEvent)
+```
+
+## ScanEvent Struct
+
+```go
+type ScanEvent struct {
+	Type     ScanEventType
+	Device   *results.DeviceInfo
+	Progress float64
+	Message  string
+}
+```
+
+## Event Types
+
+| Type | Description | Included Data |
+|------|-------------|---------------|
+| `EventLifecycleStart` | Fired once when `StartScan` is invoked. | `Message` |
+| `EventLifecycleComplete` | Fired once when `StartScan` completes successfully. | `Message` |
+| `EventLifecycleCancel` | Fired once when the scan is cancelled or times out. | `Message` |
+| `EventWarning` | Fired when a non-fatal error occurs (e.g. permission issues). | `Message` |
+| `EventProgress` | Fired periodically to indicate scan progress. | `Progress` (0.0 to 1.0) |
+| `EventResult` | Fired when a device scan completes (whether alive or dead). | `Device` |
+
+## Consumer Responsibilities
+
+1. **Non-blocking callbacks:** Event callbacks are executed synchronously by the engine's worker goroutines. Consumers **must not** perform long-blocking operations in the callback. If processing requires heavy I/O, dispatch it to a channel or separate goroutine.
+2. **Thread safety:** The `Device` pointer in `EventResult` points to a copied value, but consumers should avoid mutating it.

pkg/coreerr/errors.go

@@ -0,0 +1,13 @@
+package coreerr
+
+import "errors"
+
+// Sentinel errors representing the structured taxonomy for core operations.
+var (
+	ErrInvalidInput = errors.New("invalid input")
+	ErrTimeout      = errors.New("operation timed out")
+	ErrCancelled    = errors.New("operation cancelled")
+	ErrPermission   = errors.New("permission denied")
+	ErrExport       = errors.New("export failed")
+	ErrPartial      = errors.New("partial failure")
+)

pkg/coreerr/errors_test.go

@@ -0,0 +1,19 @@
+package coreerr
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func TestErrorWrapping(t *testing.T) {
+	err := fmt.Errorf("scan failed: %w", ErrTimeout)
+
+	if !errors.Is(err, ErrTimeout) {
+		t.Errorf("Expected err to wrap ErrTimeout, but errors.Is returned false")
+	}
+
+	if errors.Is(err, ErrCancelled) {
+		t.Errorf("Expected err to not wrap ErrCancelled")
+	}
+}

pkg/engine/events.go

@@ -6,7 +6,11 @@ import "github.com/mendsec/catnet-core/pkg/results"
 type ScanEventType int
 
 const (
-	EventResult ScanEventType = iota
+	EventLifecycleStart ScanEventType = iota
+	EventLifecycleComplete
+	EventLifecycleCancel
+	EventWarning
+	EventResult
 	EventProgress
 )
 
@@ -15,6 +19,7 @@ type ScanEvent struct {
 	Type     ScanEventType
 	Device   *results.DeviceInfo
 	Progress float64
+	Message  string
 }
 
 // EventCallback é a assinatura da função de callback síncrono.

pkg/engine/scan.go

@@ -2,10 +2,12 @@ package engine
 
 import (
 	"context"
+	"fmt"
 	"sync"
 	"sync/atomic"
 	"time"
 
+	"github.com/mendsec/catnet-core/pkg/coreerr"
 	"github.com/mendsec/catnet-core/pkg/discovery"
 	"github.com/mendsec/catnet-core/pkg/ports"
 	"github.com/mendsec/catnet-core/pkg/results"
@@ -17,8 +19,22 @@ func StartScan(ctx context.Context, ips []string, cfg ScanConfig, onEvent EventC
 	total := len(ips)
 	report.Total = total
 	report.Devices = make([]results.DeviceInfo, 0, total)
+
+	if onEvent != nil {
+		onEvent(ScanEvent{
+			Type:    EventLifecycleStart,
+			Message: "Scan started",
+		})
+	}
+
 	if total == 0 {
 		report.EndTime = time.Now()
+		if onEvent != nil {
+			onEvent(ScanEvent{
+				Type:    EventLifecycleComplete,
+				Message: "Scan completed (empty)",
+			})
+		}
 		return report, nil
 	}
 
@@ -105,5 +121,21 @@ func StartScan(ctx context.Context, ips []string, cfg ScanConfig, onEvent EventC
 	}
 	wg.Wait()
 	report.EndTime = time.Now()
+
+	if ctx.Err() == context.DeadlineExceeded {
+		if onEvent != nil {
+			onEvent(ScanEvent{Type: EventLifecycleCancel, Message: "Scan timeout"})
+		}
+		return report, fmt.Errorf("%w: scan reached timeout", coreerr.ErrTimeout)
+	} else if ctx.Err() == context.Canceled {
+		if onEvent != nil {
+			onEvent(ScanEvent{Type: EventLifecycleCancel, Message: "Scan cancelled"})
+		}
+		return report, fmt.Errorf("%w: scan was cancelled", coreerr.ErrCancelled)
+	}
+
+	if onEvent != nil {
+		onEvent(ScanEvent{Type: EventLifecycleComplete, Message: "Scan completed successfully"})
+	}
 	return report, nil
 }

pkg/exporter/exporter.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"encoding/xml"
 	"fmt"
+	"github.com/mendsec/catnet-core/pkg/coreerr"
 	"github.com/mendsec/catnet-core/pkg/results"
 	"strconv"
 	"strings"
@@ -15,7 +16,7 @@ import (
 func ExportJSON(report *results.ScanReport) ([]byte, error) {
 	out, err := json.MarshalIndent(report, "", "  ")
 	if err != nil {
-		return nil, fmt.Errorf("failed to encode JSON: %w", err)
+		return nil, fmt.Errorf("%w: failed to encode JSON: %v", coreerr.ErrExport, err)
 	}
 	return out, nil
 }
@@ -44,7 +45,7 @@ func ExportXML(report *results.ScanReport) ([]byte, error) {
 	}
 	out, err := xml.MarshalIndent(res, "", "\t")
 	if err != nil {
-		return nil, fmt.Errorf("failed to encode XML: %w", err)
+		return nil, fmt.Errorf("%w: failed to encode XML: %v", coreerr.ErrExport, err)
 	}
 	return append([]byte("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"), out...), nil
 }
@@ -65,7 +66,7 @@ func ExportCSV(report *results.ScanReport) ([]byte, error) {
 	var buf bytes.Buffer
 	writer := csv.NewWriter(&buf)
 	if err := writer.Write([]string{"IP", "Hostname", "MAC", "Status", "Open Ports"}); err != nil {
-		return nil, err
+		return nil, fmt.Errorf("%w: failed to write CSV header: %v", coreerr.ErrExport, err)
 	}
 	for _, d := range report.Devices {
 		status := "Dead"
@@ -79,7 +80,7 @@ func ExportCSV(report *results.ScanReport) ([]byte, error) {
 		if err := writer.Write([]string{
 			sanitizeCSVField(d.IP), sanitizeCSVField(d.Hostname), sanitizeCSVField(d.MAC), status, strings.Join(strPorts, ";"),
 		}); err != nil {
-			return nil, err
+			return nil, fmt.Errorf("%w: failed to write CSV record: %v", coreerr.ErrExport, err)
 		}
 	}
 	writer.Flush()

pkg/results/report.go

@@ -4,8 +4,9 @@ import "time"
 
 // ScanReport encapsula o resultado completo de uma varredura.
 type ScanReport struct {
-	StartTime time.Time    `json:"startTime"`
-	EndTime   time.Time    `json:"endTime"`
+	SchemaVersion string       `json:"schemaVersion"`
+	StartTime     time.Time    `json:"startTime"`
+	EndTime       time.Time    `json:"endTime"`
 	Total     int          `json:"total"`
 	Alive     int          `json:"alive"`
 	Devices   []DeviceInfo `json:"devices"`
@@ -14,7 +15,8 @@ type ScanReport struct {
 // NewScanReport cria um novo relatório de varredura.
 func NewScanReport() *ScanReport {
 	return &ScanReport{
-		StartTime: time.Now(),
-		Devices:   []DeviceInfo{},
+		SchemaVersion: "1.0.0",
+		StartTime:     time.Now(),
+		Devices:       []DeviceInfo{},
 	}
 }

pkg/targets/parse.go

@@ -5,13 +5,15 @@ import (
 	"fmt"
 	"net"
 	"strings"
+
+	"github.com/mendsec/catnet-core/pkg/coreerr"
 )
 
 // ParseRange interpreta uma string e retorna uma lista de endereços IP correspondentes.
 func ParseRange(input string) ([]string, error) {
 	input = strings.TrimSpace(input)
 	if input == "" {
-		return nil, fmt.Errorf("empty input")
+		return nil, fmt.Errorf("%w: empty input", coreerr.ErrInvalidInput)
 	}
 	if strings.Contains(input, "/") {
 		return parseCIDR(input)
@@ -21,7 +23,7 @@ func ParseRange(input string) ([]string, error) {
 	}
 	parsed := net.ParseIP(input)
 	if parsed == nil {
-		return nil, fmt.Errorf("invalid IP format")
+		return nil, fmt.Errorf("%w: invalid IP format", coreerr.ErrInvalidInput)
 	}
 	return []string{parsed.String()}, nil
 }
@@ -44,7 +46,7 @@ func parseCIDR(cidr string) ([]string, error) {
 func parseDashRange(dashStr string) ([]string, error) {
 	parts := strings.Split(dashStr, "-")
 	if len(parts) != 2 {
-		return nil, fmt.Errorf("invalid range format, expected start-end")
+		return nil, fmt.Errorf("%w: invalid range format, expected start-end", coreerr.ErrInvalidInput)
 	}
 	startStr := strings.TrimSpace(parts[0])
 	endStr := strings.TrimSpace(parts[1])
@@ -57,15 +59,15 @@ func parseDashRange(dashStr string) ([]string, error) {
 	startIP := net.ParseIP(startStr).To4()
 	endIP := net.ParseIP(endStr).To4()
 	if startIP == nil || endIP == nil {
-		return nil, fmt.Errorf("invalid IP in range")
+		return nil, fmt.Errorf("%w: invalid IP in range", coreerr.ErrInvalidInput)
 	}
 	start := binary.BigEndian.Uint32(startIP)
 	end := binary.BigEndian.Uint32(endIP)
 	if start > end {
-		return nil, fmt.Errorf("start IP is greater than end IP")
+		return nil, fmt.Errorf("%w: start IP is greater than end IP", coreerr.ErrInvalidInput)
 	}
 	if end-start > 65536 {
-		return nil, fmt.Errorf("range too large (max 65536)")
+		return nil, fmt.Errorf("%w: range too large (max 65536)", coreerr.ErrInvalidInput)
 	}
 	var ips []string
 	for i := start; i <= end; i++ {