// Package sources defines feedkit's input-source abstractions and source
// registry.
//
// External API surface:
//   - Input: common source identity surface
//   - PollSource: polling source interface
//   - StreamSource: streaming source interface
//   - StreamRetryable / StreamFatal / IsStreamRetryable / IsStreamFatal:
//     stream exit classification helpers
//   - Registry / NewRegistry: source driver registry and builders
//   - HTTPSource / NewHTTPSource: reusable HTTP polling helper
//   - PostgresQuerySource / NewPostgresQuerySource: reusable Postgres polling
//     helper
//
// Source drivers are domain-specific and registered into Registry by driver name.
// Registry can then build configured sources from config.SourceConfig.
//
// A single source may emit 0..N events per poll or stream iteration, and those
// events may span multiple event kinds.
//
// Optional helpers from helpers.go:
//   - DefaultEventID: default event ID policy for source implementations
//   - SingleEvent: construct and validate a one-element event slice
//   - ValidateExpectedKinds: compare configured expected kinds against source
//     advertised kinds when metadata is available
//
// HTTP-backed polling sources can share NewHTTPSource for generic HTTP config
// parsing and conditional GET behavior. The helper understands:
//   - params.url
//   - params.user_agent
//   - params.conditional (optional, default true)
//   - params.http_timeout (optional, default transport.DefaultHTTPTimeout)
//   - params.http_response_body_limit_bytes (optional, default
//     transport.DefaultHTTPResponseBodyLimitBytes)
//
// When validators are available, NewHTTPSource prefers ETag/If-None-Match and
// falls back to Last-Modified/If-Modified-Since. A 304 Not Modified response is
// treated as a successful unchanged poll.
//
// Postgres-backed polling sources can share NewPostgresQuerySource for generic
// DB config parsing and query execution. The helper understands:
//   - params.uri
//   - params.username
//   - params.password
//   - params.query
//   - params.query_timeout (optional, default 30s)
//
// feedkit does not register a built-in postgres poll driver. Downstream daemons
// should register domain-specific driver names that call
// NewPostgresQuerySource, then keep SQL semantics, row scanning, ordering,
// watermark policy, and event construction in their own source types.
package sources