// Package port defines interface contracts for external adapters.
package port

import (
	"context"
	"time"

	"github.com/orchard9/rdev/internal/domain"
)

// BuildAudit records build history for observability and debugging.
// Every build that passes through the system gets an audit entry,
// providing a complete history of what was requested, who executed it,
// and what the outcome was.
type BuildAudit interface {
	// Record creates a new audit entry when a build starts.
	Record(ctx context.Context, entry *domain.BuildAuditEntry) error

	// Update modifies an existing entry when a build completes.
	Update(ctx context.Context, taskID string, result *domain.BuildResult) error

	// Get retrieves a specific audit entry by task ID.
	// Returns ErrBuildNotFound if the entry does not exist.
	Get(ctx context.Context, taskID string) (*domain.BuildAuditEntry, error)

	// List returns audit entries matching the filter.
	List(ctx context.Context, filter BuildAuditFilter) ([]*domain.BuildAuditEntry, error)
}

// BuildAuditFilter specifies criteria for listing audit entries.
type BuildAuditFilter struct {
	// ProjectID filters entries by project.
	ProjectID string

	// WorkerID filters entries by worker.
	WorkerID string

	// Status filters entries by build status. Nil means all statuses.
	Status *domain.BuildStatus

	// Since filters entries created after this time.
	Since time.Time

	// Limit is the maximum number of entries to return.
	Limit int
}