engine

type AssetAction struct {
	Ref  AssetRef
	Mode AssetMode
}

type AssetEvent struct {
	Type          string        // e.g. asset_download, asset_stage_error, asset_rewrite
	URL           string        // asset URL (where applicable)
	Stage         string        // discover|decide|execute|rewrite
	BytesIn       int           // pre-optimization bytes
	BytesOut      int           // post-optimization bytes
	Duration      time.Duration // operation latency (download/optimize)
	Error         string        // error message if any
	Optimizations []string      // optimization identifiers applied
}

type AssetEventPublisher interface{ Publish(AssetEvent) }

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

type AssetMetricsSnapshot struct {
	Discovered      int64
	Selected        int64
	Skipped         int64
	Downloaded      int64
	Failed          int64
	Inlined         int64
	Optimized       int64
	BytesIn         int64
	BytesOut        int64
	RewriteFailures int64
}

type AssetMode int

type AssetPolicy struct {
	Enabled        bool
	MaxBytes       int64
	MaxPerPage     int
	InlineMaxBytes int64
	Optimize       bool
	RewritePrefix  string
	AllowTypes     []string
	BlockTypes     []string
	MaxConcurrent  int // Iteration 7: parallel Execute worker count (>=1). 0 => auto
}

type AssetRef struct {
	URL      string
	Type     string // e.g. img, script, stylesheet
	Attr     string // attribute name (src, href, data-src)
	Original string // original raw attribute value
}

type AssetStrategy interface {
	Discover(ctx context.Context, page *engmodels.Page) ([]AssetRef, error)
	Decide(ctx context.Context, refs []AssetRef, policy AssetPolicy) ([]AssetAction, error)
	Execute(ctx context.Context, actions []AssetAction, policy AssetPolicy) ([]MaterializedAsset, error)
	Rewrite(ctx context.Context, page *engmodels.Page, assets []MaterializedAsset, policy AssetPolicy) (*engmodels.Page, error)
	Name() string
}

type Config struct {
	// DiscoveryWorkers controls the concurrency of the seed/url discovery stage.
	// Experimental: May be folded into a single unified worker setting.
	DiscoveryWorkers int
	// ExtractionWorkers controls HTML extraction / parsing concurrency.
	// Experimental.
	ExtractionWorkers int
	// ProcessingWorkers controls post-extraction processing (enrichment, classification).
	// Experimental.
	ProcessingWorkers int
	// OutputWorkers controls the number of workers writing results to sinks.
	// Experimental.
	OutputWorkers int
	// BufferSize tunes internal channel buffering between stages.
	// Experimental: Subject to removal if adaptive backpressure is introduced.
	BufferSize int

	// RetryBaseDelay is the initial backoff delay for transient fetch failures.
	// Experimental: Retry model may be replaced by policy struct.
	RetryBaseDelay time.Duration
	// RetryMaxDelay caps the exponential backoff delay.
	// Experimental.
	RetryMaxDelay time.Duration
	// RetryMaxAttempts caps the number of retry attempts for a single fetch.
	// Experimental.
	RetryMaxAttempts int

	// RateLimit configures adaptive per-domain rate limiting.
	// Experimental: Location may change (likely to move fully under ratelimit/).
	RateLimit models.RateLimitConfig

	// Resources configures in-memory caches and spill / checkpoint behavior.
	// Experimental: Will be narrowed to higher-level policy before v1.0; implementation hidden.
	Resources ResourcesConfig

	// Resume enables filtering of already-processed seeds based on a checkpoint file.
	// Experimental: Mechanism & file format may change.
	Resume bool
	// CheckpointPath overrides Resources.CheckpointPath when non-empty.
	// Experimental.
	CheckpointPath string

	// AssetPolicy defines behavior for asset handling (Phase 5D).
	// Experimental: Entire asset subsystem is under active iteration.
	AssetPolicy AssetPolicy

	// MetricsEnabled toggles metrics collection / instrumentation.
	// Experimental: May be replaced by a Telemetry struct.
	MetricsEnabled bool
	// PrometheusListenAddr optional HTTP listen address for a Prometheus scrape endpoint.
	// Experimental: CLI layer may become the canonical place to expose endpoints.
	PrometheusListenAddr string
	// MetricsBackend selects metrics implementation: "prom" (default), "otel", or "noop".
	// Experimental: Backend selection mechanism may change.
	MetricsBackend string
}

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

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

type EngineStrategies struct {
	Fetcher     interface{} // Placeholder for crawler.Fetcher interface
	Processors  interface{} // Placeholder for []processor.Processor slice
	OutputSinks interface{} // Placeholder for []output.OutputSink slice
}

type EventBusPolicy = inttelempolicy.EventBusPolicy

type EventObserver func(ev TelemetryEvent)

type Fetcher interface {
	Fetch(ctx context.Context, url string) (*engmodels.Page, error)
}

type HealthPolicy = inttelempolicy.HealthPolicy

type LimiterDomainState struct {
	Domain       string    `json:"domain"`
	FillRate     float64   `json:"fill_rate"`
	CircuitState string    `json:"circuit_state"`
	LastActivity time.Time `json:"last_activity"`
}

type LimiterSnapshot struct {
	TotalRequests    int64                `json:"total_requests"`
	Throttled        int64                `json:"throttled"`
	Denied           int64                `json:"denied"`
	OpenCircuits     int64                `json:"open_circuits"`
	HalfOpenCircuits int64                `json:"half_open_circuits"`
	Domains          []LimiterDomainState `json:"domains,omitempty"`
}

type MaterializedAsset struct {
	Ref           AssetRef
	Bytes         []byte
	Hash          string   // sha256
	Path          string   // stable relative path
	Size          int      // size after optimization (if any)
	Optimizations []string // applied optimization identifiers
}

type OutputSink interface {
	Name() string
	Write(ctx context.Context, page *engmodels.Page) error
	Flush(ctx context.Context) error
	Close(ctx context.Context) error
}

type Processor interface {
	Process(ctx context.Context, page *engmodels.Page) (*engmodels.Page, error)
}

type ResourceSnapshot struct {
	CacheEntries     int `json:"cache_entries"`
	SpillFiles       int `json:"spill_files"`
	InFlight         int `json:"in_flight"`
	CheckpointQueued int `json:"checkpoint_queued"`
}

type ResourcesConfig struct {
	CacheCapacity      int
	MaxInFlight        int
	SpillDirectory     string
	CheckpointPath     string
	CheckpointInterval time.Duration
}

type ResumeSnapshot struct {
	SeedsBefore int   `json:"seeds_before"`
	Skipped     int64 `json:"skipped"`
}

type Snapshot struct {
	StartedAt time.Time                    `json:"started_at"`
	Uptime    time.Duration                `json:"uptime"`
	Pipeline  *engpipeline.PipelineMetrics `json:"pipeline,omitempty"`
	Limiter   *LimiterSnapshot             `json:"limiter,omitempty"`
	Resources *ResourceSnapshot            `json:"resources,omitempty"`
	Resume    *ResumeSnapshot              `json:"resume,omitempty"`
}

type TelemetryEvent struct {
	Time     time.Time              `json:"time"`
	Category string                 `json:"category"`
	Type     string                 `json:"type"`
	Severity string                 `json:"severity,omitempty"`
	TraceID  string                 `json:"trace_id,omitempty"`
	SpanID   string                 `json:"span_id,omitempty"`
	Labels   map[string]string      `json:"labels,omitempty"`
	Fields   map[string]interface{} `json:"fields,omitempty"`
}

type TelemetryOptions struct {
	EnableMetrics   bool
	EnableTracing   bool
	EnableEvents    bool
	EnableHealth    bool
	MetricsBackend  string
	SamplingPercent float64
}

type TelemetryPolicy = inttelempolicy.TelemetryPolicy

type TracingPolicy = inttelempolicy.TracingPolicy