interfaces

type AdaptiveThrottler interface {
	// Do runs op unless the throttler decides to reject it locally, in which case it returns a
	// coded "throttled" rejection (see adaptivethrottle) WITHOUT invoking op. Each op outcome
	// (accepted/rejected by the backend) feeds the accept-rate window that drives the decision.
	Do(ctx context.Context, op func() error) error
}

type AnyJob interface {
	// Named supplies the job's identity (Meta) for display and tool resolution.
	Named

	// Execute runs the job against runner (rooted at root) and returns collected
	// step results.
	Execute(
		ctx context.Context,
		runner CommandRunner,
		root string,
	) (types.StepResults, error)
}

type BufferedMessage struct {
	// ID is the message's per-connection monotonic id (e.g. "msg-7").
	ID string
	// Payload is the marshaled frame to resend unchanged (encoding-independent bytes).
	Payload []byte
}

type Bulkhead interface {
	// Execute runs fn within the concurrency limit. Blocks until a slot is
	// available or ctx is cancelled.
	Execute(ctx context.Context, fn func() error) error

	// TryExecute attempts to run fn without blocking. Returns an error if no
	// slots are available.
	TryExecute(fn func() error) error
}

type ByteCache interface {
	// Get retrieves a value by key. Returns (nil, false) if not found or expired.
	Get(ctx context.Context, key string) ([]byte, bool)

	// Set stores a value with the given TTL.
	Set(ctx context.Context, key string, value []byte, ttl time.Duration)

	// Delete removes a value by key.
	Delete(ctx context.Context, key string)
}

type Cache[T any] interface {
	// Get retrieves a value by key. Returns (zero-value, false) if not found or expired.
	Get(ctx context.Context, key string) (T, bool)

	// Set stores a value with the given TTL. TTL of 0 means no expiration.
	Set(ctx context.Context, key string, value T, ttl time.Duration) error

	// Delete removes a value by key.
	Delete(ctx context.Context, key string) error

	// Exists checks if a key exists and is not expired.
	Exists(ctx context.Context, key string) bool
}

type CacheInvalidator interface {
	// InvalidatePrefix removes all keys matching the given prefix.
	InvalidatePrefix(ctx context.Context, prefix string) error

	// InvalidateAll clears the entire cache.
	InvalidateAll(ctx context.Context) error
}

type CircuitBreaker interface {
	// Execute runs fn through the circuit breaker. Returns an error if the
	// circuit is open or fn fails.
	Execute(fn func() error) error
}

type Client interface {
	// Lifecycle provides coordinated Start/Stop.
	Lifecycle
	// HealthChecker provides the Kubernetes Liveness/Readiness probes.
	HealthChecker
}

type CmdHook interface {
	// OnStart is called immediately before a command is launched.
	// cmdStr is the full command string (name + joined args).
	OnStart(cmdStr string)

	// OnSuccess is called when a command exits with a zero exit code.
	OnSuccess(cmdStr string)

	// OnFailure is called when a command exits with a non-zero exit code.
	OnFailure(cmdStr string)
}

type CmdResult struct {
	// Err is the error returned by the command, or nil on success.
	Err error

	// Stdout is the captured standard output.
	Stdout []byte

	// Stderr is the captured standard error.
	Stderr []byte

	// Duration is the wall-clock time the command took to execute.
	Duration time.Duration

	// ExitCode is the process exit code: 0 on success, the process's code on a
	// non-zero exit, or -1 when the command could not be started or did not exit
	// normally. Lets callers branch on specific codes (e.g. pytest's 5 = "no
	// tests collected") without parsing Err.
	ExitCode int
}

type CommandRunner interface {
	// Run executes a command with inherited stdout/stderr.
	Run(ctx context.Context, dir, name string, args ...string) error

	// RunWithEnv executes a command with additional environment variables.
	RunWithEnv(
		ctx context.Context,
		dir string,
		extraEnv []string,
		name string,
		args ...string,
	) error

	// RunBuffered executes a command with captured stdout/stderr.
	RunBuffered(ctx context.Context, dir, name string, args ...string) CmdResult

	// RunBufferedWithEnv executes a command with additional environment
	// variables and captured stdout/stderr.
	RunBufferedWithEnv(
		ctx context.Context,
		dir string,
		extraEnv []string,
		name string,
		args ...string,
	) CmdResult

	// Exists checks whether a binary is available on PATH.
	Exists(name string) bool

	// RequireTool returns an error if the named binary is not on PATH.
	RequireTool(name, installHint string) error
}

type CompletedPart struct {
	// ETag is the entity tag S3 returned from the part's UploadPart request.
	ETag string `json:"etag"`
	// PartNumber is the part's 1-based index within the multipart upload.
	PartNumber int32 `json:"part_number"`
}

type ConfigLoader interface {
	// Get returns the raw value for a key, or nil if not set.
	Get(key string) any

	// GetString returns the string value for a key.
	GetString(key string) string

	// GetInt returns the int value for a key.
	GetInt(key string) int

	// GetBool returns the bool value for a key.
	GetBool(key string) bool

	// Unmarshal decodes the full configuration into the target struct.
	Unmarshal(target any) error

	// UnmarshalKey decodes a specific configuration section into the target struct.
	// The key parameter is a dot-separated path (e.g., "database", "server.identity").
	UnmarshalKey(key string, target any) error
}

type ConnectorKind string

type ConnectorSource interface {
	// TestConnection probes the source with the connector's credentials and returns a bounded count
	// of reachable items (e.g. objects under an S3 bucket/prefix), or a coded error when the source
	// is unreachable or the credentials are rejected.
	TestConnection(ctx context.Context) (int, error)

	// ListPage streams one page of the source's objects starting AFTER continuationToken (empty = the
	// start of the listing) and returns the page plus the token to resume from ("" when the listing is
	// exhausted). It is the resumable, memory-bounded primitive a sync process crawls a large source
	// with — holding one page at a time (never the full key list) and checkpointing the token so a
	// crashed sync resumes from the last committed page rather than restarting a million-object crawl.
	// A non-positive limit lets the backend apply its default page size. A failure is a coded error
	// (transient CodeUnavailable vs terminal CodeInvalidInput) so the caller can classify retry-vs-fail.
	ListPage(
		ctx context.Context,
		continuationToken string,
		limit int,
	) (objects []StorageObject, nextToken string, err error)
}

type Counter interface {
	// Inc increments the counter by 1 with the given label values.
	Inc(labelValues ...string)

	// Add increments the counter by the given value.
	Add(value float64, labelValues ...string)
}

type CountingPublisher interface {
	// MessagePublisher provides the base Publish/PublishBatch operations.
	MessagePublisher

	// PublishCount sends payload to topic and returns the number of subscribers that
	// received it (0 when no subscriber is listening). For Redis Pub/Sub this is the
	// PUBLISH reply; a positive count means the message was delivered to at least one
	// subscriber.
	PublishCount(ctx context.Context, topic string, payload []byte) (int, error)
}

type DatabasePool interface {
	// Client supplies the Start/Stop lifecycle and Kubernetes health probes.
	Client

	// DB returns the underlying *sql.DB the ORM adapters and raw-SQL callers share.
	// It is nil until Start opens the pool.
	DB() *sql.DB
}

type DeadLetter struct {
	// ID identifies the dead-lettered message (typically the source message id).
	ID string
	// Reason records why processing failed and the message was dead-lettered.
	Reason string
	// Payload is the original message body, preserved for inspection or redrive.
	Payload []byte
}

type DeadLetterBackend interface {
	// Send durably records the dead letter, returning an error if the sink is
	// unavailable so the caller can decide delete-vs-redrive of the source message.
	Send(ctx context.Context, letter DeadLetter) error
}

type DecoratedRepository[T any, P any, ID comparable] interface {
	// Repository is the base CRUD surface the decorator stack wraps.
	Repository[T, P, ID]
}

type DecoratedService[T any, P any, ID comparable] interface {
	// Service is the base CRUD surface the decorator stack wraps.
	Service[T, P, ID]
}

type Deduplicator interface {
	// Seen atomically reports whether key was already processed and, if not, marks it
	// processed. It returns true when key is a duplicate (the caller should skip it) and
	// false when this is the first sighting (the caller should process it).
	Seen(ctx context.Context, key string) (bool, error)
}

type Deleter[ID comparable] interface {
	// Delete removes an entity by ID.
	Delete(ctx context.Context, id ID) error
}

type Discoverer[T any] interface {
	// Discover returns the work units found under root.
	Discover(ctx context.Context, root string) ([]T, error)
}

type DiscovererFunc[T any] func(ctx context.Context, root string) ([]T, error)

type DistributedLock interface {
	// Acquire attempts to take key without blocking. On success it returns an
	// opaque fencing token and acquired=true; if the key is already held it
	// returns an empty token and acquired=false. The token must be presented to
	// Renew and Release so a previous holder cannot affect the current one.
	Acquire(ctx context.Context, key string) (token string, acquired bool, err error)

	// Renew extends the lease on key iff token still holds it. held=true means
	// the caller still owns the lock; held=false means the lease was lost (it
	// expired, was released, or a different holder now owns the key) and the
	// caller must stop treating itself as the holder. err is reserved for
	// backend/transport failures, distinct from a cleanly lost lease.
	Renew(ctx context.Context, key, token string) (held bool, err error)

	// Release frees key iff token still holds it (token-fenced). Releasing a key
	// held by a different token, or an unheld key, is a no-op — never an error —
	// so a late Release from a previous holder cannot free a new holder's lock.
	Release(ctx context.Context, key, token string) error
}

type DynamicConsumer interface {
	// MessageConsumer provides the base Subscribe/Close operations.
	MessageConsumer

	// Unsubscribe stops delivering messages from topic. It is a no-op if topic
	// was never subscribed; a broker error is returned.
	Unsubscribe(ctx context.Context, topic string) error
}

type Encryptor interface {
	// Encrypt seals plaintext, returning a nonce-prefixed ciphertext.
	Encrypt(plaintext []byte) ([]byte, error)
	// Decrypt opens a ciphertext produced by Encrypt, returning the original plaintext.
	// It errors on a wrong key or a tampered ciphertext.
	Decrypt(ciphertext []byte) ([]byte, error)
}

type EventPublisher interface {
	// Publish publishes a single domain event.
	Publish(ctx context.Context, event events.Event) error

	// PublishBatch publishes multiple domain events.
	PublishBatch(ctx context.Context, events []events.Event) error
}

type ExecutionObserver interface {
	// OnGateStart is called once when the gate begins, before any phase runs,
	// with the names of the phases it will execute.
	OnGateStart(name string, phases []string)

	// OnPhaseStart is called once when a phase begins, before any job runs,
	// with the names of the jobs it will execute.
	OnPhaseStart(name string, jobs []string)

	// OnStepStart is called when an individual step begins, before it runs.
	// Best-effort: producers that don't know a step's name up front may skip it.
	OnStepStart(name, group string)

	// OnStepComplete is called after each individual step finishes.
	OnStepComplete(result types.StepResult)

	// OnPhaseComplete is called once after all jobs in a gate phase finish,
	// with the phase's aggregate results and measured wall-clock elapsed.
	OnPhaseComplete(name string, results types.StepResults, elapsed time.Duration)

	// OnGateComplete is called when the full gate (all phases) finishes, with the
	// gate's aggregate results and measured total wall-clock elapsed.
	OnGateComplete(gateName string, results types.StepResults, elapsed time.Duration)
}

type Exister[ID comparable] interface {
	// Exists checks if an entity with the given ID exists.
	Exists(ctx context.Context, id ID) (bool, error)
}

type FS interface {
	// Stat returns a FileInfo describing the named file.
	Stat(name string) (fs.FileInfo, error)

	// MkdirAll creates a directory named path, along with any necessary parents.
	MkdirAll(path string, perm fs.FileMode) error

	// ReadFile reads the named file and returns the contents.
	ReadFile(name string) ([]byte, error)

	// WriteFile writes data to the named file, creating it if necessary.
	WriteFile(name string, data []byte, perm fs.FileMode) error

	// RemoveAll removes path and any children it contains.
	RemoveAll(path string) error

	// Rename renames (moves) oldpath to newpath.
	Rename(oldpath, newpath string) error

	// ReadDir reads the named directory and returns all its directory entries
	// sorted by filename.
	ReadDir(name string) ([]fs.DirEntry, error)
}

type Gauge interface {
	// Set sets the gauge to the given value.
	Set(value float64, labelValues ...string)

	// Inc increments the gauge by 1.
	Inc(labelValues ...string)

	// Dec decrements the gauge by 1.
	Dec(labelValues ...string)
}

type GitOps interface {
	// HasPathsChanged reports whether any of the given paths differ between
	// two git refs. Returns true when differences exist.
	HasPathsChanged(
		ctx context.Context,
		root, from, to string,
		paths []string,
	) (bool, error)

	// StageFiles runs git add on the given paths relative to root.
	StageFiles(ctx context.Context, root string, paths []string) error

	// StagedFiles returns root-relative paths of staged files matching the
	// given glob patterns (e.g., "*.go", "*.py").
	StagedFiles(ctx context.Context, root string, patterns []string) ([]string, error)
}

type HealthChecker interface {
	// Liveness reports whether the component is alive (a lightweight self-check that
	// does not depend on external systems).
	Liveness(ctx context.Context) error

	// Readiness reports whether the component can serve traffic — typically by
	// verifying connectivity (e.g. a Ping).
	Readiness(ctx context.Context) error
}

type Hedger interface {
	// Hedge runs op, racing a second concurrent attempt after the configured delay, and
	// returns the result of the first attempt to complete. The slower attempt is cancelled
	// via ctx. Returns the first responder's error, or ctx's error if it is cancelled first.
	Hedge(ctx context.Context, op func() error) error
}

type Histogram interface {
	// Observe records a value with the given label values.
	Observe(value float64, labelValues ...string)
}

type Inserter[T any] interface {
	// Insert persists a new entity; append-only, so it returns only an error.
	Insert(ctx context.Context, entity *T) error
}

type Job interface {
	// Kind returns the job type identifier used for worker dispatch.
	Kind() string

	// Args returns the job's payload as a key-value map.
	Args() map[string]interface{}
}

type JobEnqueuer interface {
	// Enqueue submits a job for asynchronous processing.
	Enqueue(ctx context.Context, job Job) error

	// Close releases resources held by the enqueuer.
	Close() error
}

type JobFactory interface {
	// Job builds and returns the configured AnyJob.
	Job() AnyJob
}

type JobScheduler interface {
	// Schedule adds a periodic job to the schedule at the given interval.
	Schedule(job PeriodicJob, interval time.Duration) error
}

type LeaderElector interface {
	// IsLeader reports whether this instance currently holds leadership.
	IsLeader(ctx context.Context) (bool, error)
}

type Lifecycle interface {
	// Start initializes the component and establishes its connection/resources. It
	// should block until the component is ready or ctx is cancelled.
	Start(ctx context.Context) error

	// Stop gracefully releases the component's resources and completes in-flight
	// work.
	Stop(ctx context.Context) error
}

type ListRunner[T any] interface {
	// List applies the resolved spec (predicates + order + window) to the scoped base query and
	// returns the matching rows in order.
	List(ctx context.Context, spec types.ListSpec) ([]T, error)

	// Count returns the number of rows matching the given resolved predicates over the scoped base
	// query (no window), for the offset pager's total_count — BOUNDED at `bound` (≥ 1): it counts at
	// most `bound` rows (a LIMIT-bounded id fetch, O(bound)), so a per-page total_count never pays a
	// full-table COUNT on a huge set. The caller (foundation/listquery.Run) passes
	// count_cap+1 and turns an over-cap tally into an estimate; the runner just reports the bounded
	// tally.
	Count(ctx context.Context, filters []types.Filter, bound int) (int, error)
}

type Lister[T any, P any] interface {
	// List retrieves entities matching the given parameters with pagination.
	List(ctx context.Context, params P, page types.PageRequest) (*types.Page[T], error)
}

type Locker interface {
	// DistributedLock provides the primitive Acquire/Renew/Release operations.
	DistributedLock

	// Hold acquires key and, on success, keeps its lease alive with a background
	// watchdog that renews on the configured interval. It returns:
	//   - held: a child of ctx that is cancelled the instant the lease is lost (a
	//     Renew reports held=false or errors) or when release is called; run the
	//     guarded work under held so it stops the moment the lock is no longer ours.
	//   - release: stops the watchdog, cancels held, and frees the lock
	//     (token-fenced); idempotent, safe to defer, and frees the key even if ctx
	//     is already cancelled.
	//   - acquired: false if the key was already held by someone else (held is then
	//     a cancelled context and release a no-op — the caller should reject the
	//     request); err is returned only for a backend failure on Acquire.
	Hold(
		ctx context.Context,
		key string,
	) (held context.Context, release func(), acquired bool, err error)
}

type Logger interface {
	// Debug logs at DEBUG level with optional key-value pairs.
	Debug(msg string, keysAndValues ...any)

	// Info logs at INFO level with optional key-value pairs.
	Info(msg string, keysAndValues ...any)

	// Warn logs at WARN level with optional key-value pairs.
	Warn(msg string, keysAndValues ...any)

	// Error logs at ERROR level with optional key-value pairs.
	Error(msg string, keysAndValues ...any)

	// With returns a new Logger with the given key-value pairs pre-bound.
	With(keysAndValues ...any) Logger

	// WithContext returns a new Logger that extracts values (e.g. correlation ID)
	// from the context on each log call.
	WithContext(ctx context.Context) Logger
}

type Message struct {
	// Metadata holds optional key-value pairs attached to the message.
	Metadata map[string]string `json:"metadata,omitempty"`

	// ID is the unique identifier of the message.
	ID string `json:"id"`

	// Topic is the queue or topic the message was received from.
	Topic string `json:"topic"`

	// Payload is the raw message body.
	Payload []byte `json:"payload"`

	// Timestamp is the Unix timestamp when the message was produced.
	Timestamp int64 `json:"timestamp"`
}

type MessageConsumer interface {
	// Subscribe starts consuming messages from the specified topic.
	// The handler is called for each message. Return nil to ack, error to nack.
	Subscribe(ctx context.Context, topic string, handler MessageHandler) error

	// Close stops the consumer gracefully.
	Close() error
}

type MessageHandler func(ctx context.Context, msg *Message) error

type MessagePublisher interface {
	// Publish sends a message to the specified topic.
	Publish(ctx context.Context, topic string, payload []byte) error

	// PublishBatch sends multiple messages to the specified topic.
	PublishBatch(ctx context.Context, topic string, payloads [][]byte) error
}

type Metrics interface {
	// Counter returns a counter that can be incremented.
	Counter(name, help string, labels ...string) Counter

	// Histogram returns a histogram for recording distributions.
	Histogram(name, help string, buckets []float64, labels ...string) Histogram

	// Gauge returns a gauge for recording point-in-time values.
	Gauge(name, help string, labels ...string) Gauge

	// Handler returns an HTTP handler that serves the metrics endpoint.
	Handler() http.Handler
}

type MultipartUpload struct {
	// Key is the object key the upload will assemble into.
	Key string `json:"key"`

	// UploadID is the S3 multipart upload id (needed to abort or complete it).
	UploadID string `json:"upload_id"`

	// Initiated is the RFC3339 timestamp the upload was created, or "" if unknown.
	Initiated string `json:"initiated"`
}

type Named interface {
	// Meta returns the unit's identity for display and tool resolution.
	Meta() types.JobMeta
}

type OpService[A any, R any] interface {
	// Name returns the service name, used as a label in logs, metrics, and
	// decorator actions.
	Name() string

	// Run executes the operation described by args and returns its result. It is
	// the single decoration chokepoint: cross-cutting concerns (logging, metrics,
	// tracing, recovery) wrap Run rather than each individual operation.
	Run(ctx context.Context, args A) (R, error)
}

type PatternConsumer interface {
	// DynamicConsumer provides the base consume operations plus per-channel Unsubscribe.
	DynamicConsumer

	// PSubscribe starts delivering messages from every channel matching pattern
	// (glob syntax) to handler. Runtime add.
	PSubscribe(ctx context.Context, pattern string, handler MessageHandler) error

	// PUnsubscribe stops delivering messages for pattern. It is a no-op if pattern
	// was never subscribed; a broker error is returned. Runtime remove.
	PUnsubscribe(ctx context.Context, pattern string) error
}

type PeriodicJob struct {
	// Args holds arbitrary key-value arguments passed to the job worker.
	Args map[string]interface{}

	// Kind is the job type identifier used to match a registered worker.
	Kind string

	// Schedule is a cron expression defining when the job runs.
	Schedule string
}

type Pipeline[In any, Out any] interface {
	// Execute transforms the input into output.
	// Context is provided for cancellation and tracing.
	// Implementations should be stateless and safe for concurrent use.
	Execute(ctx context.Context, input In) (Out, error)
}

type QueryBackend[Q, S any] interface {
	// Clause interprets a single leaf comparison — storage column <op> value — into a predicate.
	// col is already resolved from the allow-list; v is the parser-validated operand (a scalar,
	// or a []any for OpIn/OpNotIn).
	Clause(col string, op types.FilterOperator, v any) Q

	// ExistsClause interprets a leaf comparison whose column lives on a JOINED table into a
	// correlated EXISTS predicate: the base row matches when a row in join.Table (correlated by
	// join.TargetKey = <base>.join.LocalKey) satisfies op/v on one of join.Columns (ORed when >1). It
	// never joins the base query, so scope/soft-delete/keyset are untouched. v is the parser-validated
	// operand (a scalar, or a []any for OpIn/OpNotIn), same as Clause.
	ExistsClause(join types.JoinTarget, op types.FilterOperator, v any) Q

	// And combines sub-predicates so that every one must match.
	And(subs []Q) Q

	// Or combines sub-predicates so that at least one must match.
	Or(subs []Q) Q

	// Empty is the no-op (match-all) predicate for an absent or empty filter.
	Empty() Q

	// Order interprets one sort directive — storage column, descending when desc — into a sort node.
	Order(col string, desc bool) S

	// OrderJoin interprets a sort directive whose column lives on a JOINED table into a sort
	// node that orders by a correlated subquery over join.Table (correlated by join.TargetKey =
	// <base>.join.LocalKey), one ORDER BY term per join.Columns entry (a member "name" over
	// first_name+last_name). Like ExistsClause it never joins the base query. Joined sorts always ride
	// the offset pager (keyset stays same-table), so no keyset-seek counterpart is needed.
	OrderJoin(join types.JoinTarget, desc bool) S

	// OrderOrdinal interprets a sort directive with a value ORDINAL into a sort node that
	// orders col by the given values' positions (`CASE col WHEN v0 THEN 0 … ELSE len END`), so an enum
	// column sorts by meaning (owner<editor<viewer) rather than alphabetically. values are the column's
	// DB values in ascending order. An ordinal sort is a custom sort (the offset pager); no keyset seek.
	OrderOrdinal(col string, values []string, desc bool) S

	// OrderDerived interprets a COMPUTED / CORRELATED sort directive into a sort node: a
	// correlated aggregate over a child table (d.Aggregate — a Documents/Members COUNT) or a
	// timestamp-plus-interval (d.Interval — a connector's Next Sync = last_sync_at + the schedule's
	// interval). Exactly one arm of d is set. Like OrderJoin it renders an ORDER BY over an expression /
	// correlated subquery and never joins the base query; a derived sort is a custom sort (the offset
	// pager), so there is no keyset-seek counterpart.
	OrderDerived(d types.DerivedSort, desc bool) S
}

type RateLimiter interface {
	// Allow reports whether an event may happen now (non-blocking).
	Allow() bool

	// Wait blocks until the limiter permits an event or ctx is cancelled.
	Wait(ctx context.Context) error
}

type Reader[T any, ID comparable] interface {
	// Get retrieves an entity by ID.
	Get(ctx context.Context, id ID) (*T, error)
}

type ReplayBuffer interface {
	// Append records payload (identified by msgID) as the newest entry under key, evicting the
	// oldest beyond the configured bound and refreshing the key's TTL.
	Append(ctx context.Context, key, msgID string, payload []byte) error

	// ReplayAfter returns the retained messages strictly after afterMsgID, in insertion order.
	// complete is true only when afterMsgID is a proven-gapless anchor — either present in the
	// retained window (a gapless tail follows, possibly empty when the caller is already caught up)
	// or exactly the low-water mark set by the last Prune. complete is false for anything else —
	// an evicted or unknown id, a TTL-expired or absent key, or an empty afterMsgID (a client that
	// received nothing; unreachable in practice) — so the caller must full-refresh, never replay a
	// possibly-gapped tail. complete=false is always the safe answer.
	ReplayAfter(
		ctx context.Context,
		key, afterMsgID string,
	) (msgs []BufferedMessage, complete bool, err error)

	// Prune drops every retained entry up to and including upToMsgID — a confirmed prefix the client
	// has acked — leaving the tail, and records upToMsgID as the new low-water mark. An upToMsgID not
	// in the retained window is a no-op.
	Prune(ctx context.Context, key, upToMsgID string) error

	// Delete removes the key's buffer entirely (e.g. after a successful replay).
	Delete(ctx context.Context, key string) error
}

type Repository[T any, P any, ID comparable] interface {
	// Reader provides Get (retrieve by id).
	Reader[T, ID]
	// Lister provides List (paginated query by params).
	Lister[T, P]
	// Writer provides Create and Update.
	Writer[T, ID]
	// Deleter provides Delete (remove by id).
	Deleter[ID]
	// Exister provides Exists (existence check by id).
	Exister[ID]
}

type Retrier interface {
	// Retry executes op with automatic retry on transient failures.
	// Returns nil on success, or the last error after all retries are exhausted.
	Retry(ctx context.Context, op func() error) error
}

type Runnable interface {
	// Named supplies the unit's identity (Meta) for display and tool resolution.
	Named

	// Run performs the unit's in-process work and returns collected step results.
	Run(ctx context.Context) (types.StepResults, error)
}

type ServerTransport interface {
	// Client supplies the Start/Stop lifecycle and Kubernetes health probes.
	Client

	// RegisterFunc mounts an http.HandlerFunc at a path pattern.
	RegisterFunc(pattern string, handler http.HandlerFunc)

	// Mux returns the underlying request multiplexer for direct handler registration
	// (e.g. mounting a generated Connect handler at its path prefix).
	Mux() *http.ServeMux
}

type Service[T any, P any, ID comparable] interface {
	// Reader provides Get (retrieve by id).
	Reader[T, ID]
	// Lister provides List (paginated query by params).
	Lister[T, P]
	// Writer provides Create and Update.
	Writer[T, ID]
	// Deleter provides Delete (remove by id).
	Deleter[ID]
}

type ServiceHooks[T any] interface {
	// BeforeCreate is called before entity creation. Can modify the entity or return an error.
	BeforeCreate(ctx context.Context, entity *T) error

	// AfterCreate is called after successful entity creation.
	AfterCreate(ctx context.Context, entity *T) error

	// BeforeUpdate is called before entity update. Can modify the entity or return an error.
	BeforeUpdate(ctx context.Context, entity *T) error

	// AfterUpdate is called after successful entity update.
	AfterUpdate(ctx context.Context, entity *T) error

	// BeforeDelete is called before entity deletion.
	BeforeDelete(ctx context.Context, id any) error

	// AfterDelete is called after successful entity deletion.
	AfterDelete(ctx context.Context, id any) error
}

type ServiceTokenValidator interface {
	// Validate returns the calling service's name for a valid token, or ok=false when
	// the token matches no known caller.
	Validate(token string) (caller string, ok bool)
}

type Source interface {
	// Get resolves the credential referenced by ref, returned as an opaque Secret. A
	// missing credential is a coded not-found error, not an empty Secret.
	Get(ctx context.Context, ref types.Ref) (types.Secret, error)

	// Put stores value for ref. Read-only backends (environment variables, and cloud
	// secret managers written out-of-band by IaC) return a coded unsupported-operation
	// error rather than silently succeeding.
	Put(ctx context.Context, ref types.Ref, value types.Secret) error
}

type SourceBuilder interface {
	// Build constructs the ConnectorSource for cfg.Kind, or returns a coded error on an unknown kind
	// or a construction failure.
	Build(ctx context.Context, cfg SourceConfig) (ConnectorSource, error)
}

type SourceConfig struct {
	// Kind selects the connector backend.
	Kind ConnectorKind
	// Bucket names the source object-store bucket (S3 kind).
	Bucket string
	// Prefix restricts the listing to objects under this key prefix (S3 kind).
	Prefix string
	// Region is the connector's bucket region (S3 kind); empty falls back to the client default. The
	// object-store ENDPOINT is deliberately NOT here — it is app-infra (dev MinIO), captured by the
	// composition root's client builder, not a per-connector value.
	Region string
	// AuthMethod selects the credential strategy: "iam_role" (STS AssumeRole) or "access_key" (static).
	AuthMethod string
	// IAMRoleARN is the role assumed for auth_method=iam_role.
	IAMRoleARN string
	// ExternalID is the STS ExternalId sent on every AssumeRole for auth_method=iam_role
	// (required there). The role's trust policy requires it, which ties the role to the
	// tenant that owns it: without it, a tenant who registers another tenant's role ARN
	// could have the platform assume it for them (the confused-deputy problem). The
	// consumer's platform generates it per tenant and stores it with the connector; it is
	// never taken from tenant input, or a tenant could present another tenant's role ARN
	// together with that tenant's id. Format (STS's rule): 2–1224 characters of
	// [\w+=,.@:/-]; the S3 builder rejects anything else with CodeInvalidInput.
	ExternalID string
	// AccessKeyID is the access key id for auth_method=access_key.
	AccessKeyID string
	// SecretAccessKey is the secret for auth_method=access_key (already-decrypted plaintext; never log it).
	SecretAccessKey string
}

type Span interface {
	// End completes the span.
	End()

	// SetAttribute adds a key-value attribute to the span.
	SetAttribute(key string, value any)

	// RecordError records an error on the span.
	RecordError(err error)

	// SetStatus sets the span status.
	SetStatus(code SpanStatusCode, description string)
}

type SpanConfig struct {
	// Kind specifies the span kind (client, server, producer, consumer, internal).
	Kind SpanKind
}

type SpanKind int

type SpanOption func(*SpanConfig)

type SpanStatusCode int

type StorageClient interface {
	// Upload stores an object with the given key in the specified bucket.
	Upload(
		ctx context.Context,
		bucket, key string,
		body io.Reader,
		contentType string,
	) error

	// Download retrieves an object by key from the specified bucket.
	Download(ctx context.Context, bucket, key string) (io.ReadCloser, error)

	// Delete removes an object by key from the specified bucket.
	Delete(ctx context.Context, bucket, key string) error

	// DeleteBatch removes multiple objects by key in a single request. It is the
	// efficient path for cleanup operations (e.g. orphaned-file reconciliation).
	DeleteBatch(ctx context.Context, bucket string, keys []string) error

	// Exists checks if an object exists at the given key.
	Exists(ctx context.Context, bucket, key string) (bool, error)

	// Stat returns metadata (content-type, size, etag, last-modified) for an object
	// without downloading its body. Returns errors.ErrNotFound when the key is absent.
	Stat(ctx context.Context, bucket, key string) (StorageObject, error)

	// PresignURL generates a pre-signed URL for temporary GET (download) access to
	// an object. The URL expires after the specified duration (in seconds).
	//
	// When displayFilename is non-empty the URL is signed with a
	// response-content-disposition of `attachment; filename="…"`, so S3 returns that
	// header on the GET and the browser downloads the object (under the given name)
	// instead of rendering it inline. An empty displayFilename leaves the disposition
	// unset (inline). The override is part of the SigV4 signature, so it must be set
	// here at presign time — a client cannot append it to the URL after the fact.
	PresignURL(
		ctx context.Context,
		bucket, key string,
		expirySeconds int,
		displayFilename string,
	) (string, error)

	// PresignPutURL generates a pre-signed URL for temporary PUT (upload) access,
	// allowing direct browser-to-storage uploads. The URL expires after the
	// specified duration (in seconds); contentType pins the upload's Content-Type.
	PresignPutURL(
		ctx context.Context,
		bucket, key string,
		expirySeconds int,
		contentType string,
	) (string, error)

	// CreateMultipartUpload begins a browser-direct multipart upload and returns its
	// S3 upload id. The caller presigns each part with PresignUploadPart and later
	// finalizes with CompleteMultipartUpload (or discards with AbortMultipartUpload).
	CreateMultipartUpload(
		ctx context.Context,
		bucket, key, contentType string,
	) (string, error)

	// PresignUploadPart generates a pre-signed PUT URL for one part (1-based
	// partNumber) of the multipart upload identified by uploadID. The URL expires
	// after expirySeconds; the browser PUTs the part bytes to it and reads the
	// returned ETag (which the bucket CORS must expose).
	PresignUploadPart(
		ctx context.Context,
		bucket, key, uploadID string,
		partNumber int32,
		expirySeconds int,
	) (string, error)

	// CompleteMultipartUpload finalizes the multipart upload identified by uploadID,
	// assembling the client-reported parts into the object at key. Parts must be
	// ordered by ascending part number.
	CompleteMultipartUpload(
		ctx context.Context,
		bucket, key, uploadID string,
		parts []CompletedPart,
	) error

	// AbortMultipartUpload discards the in-progress multipart upload identified by
	// uploadID, releasing its already-uploaded parts.
	AbortMultipartUpload(ctx context.Context, bucket, key, uploadID string) error

	// ListMultipartUploads lists the in-progress (not yet completed or aborted)
	// multipart uploads in a bucket, so a cleanup sweep can abort abandoned ones —
	// which are invisible to ListObjects until completed.
	ListMultipartUploads(ctx context.Context, bucket string) ([]MultipartUpload, error)

	// ListObjects lists objects in a bucket with the given prefix.
	ListObjects(ctx context.Context, bucket, prefix string) ([]StorageObject, error)

	// ListObjectsPage lists AT MOST limit objects in a bucket with the given prefix — a bounded
	// single-page variant of ListObjects for callers that need a cheap reachability/count probe
	// rather than a full inventory (e.g. a connector's TestConnection against a large customer
	// bucket). A non-positive limit lists at most one page's worth (backend default).
	ListObjectsPage(
		ctx context.Context,
		bucket, prefix string,
		limit int,
	) ([]StorageObject, error)

	// ListObjectsPageToken lists AT MOST limit objects under prefix STARTING AFTER continuationToken
	// (empty token = start of the listing) and returns the objects plus the token to resume from
	// (nextToken == "" when the listing is exhausted). It is the resumable, memory-bounded streaming
	// primitive a large-bucket crawl pages over — never materializing the full key list — so a caller
	// (e.g. a sync engine) holds at most one page at a time and can checkpoint the token to
	// crash-resume. A non-positive limit lets the backend apply its default page size.
	ListObjectsPageToken(
		ctx context.Context,
		bucket, prefix, continuationToken string,
		limit int,
	) (objects []StorageObject, nextToken string, err error)

	// EnsureBucket creates the named bucket if it does not already exist,
	// idempotently (a concurrently-created bucket is treated as success). It exists
	// so local/dev provisioning — e.g. a seeding tool — can guarantee an upload
	// path has its bucket before the first presigned PUT.
	EnsureBucket(ctx context.Context, bucket string) error
}

type StorageObject struct {
	// Key is the object's storage key (path) in the bucket.
	Key string `json:"key"`

	// ContentType is the MIME type of the object.
	ContentType string `json:"content_type"`

	// LastModified is the timestamp of the last modification.
	LastModified string `json:"last_modified"`

	// ETag is the entity tag for cache validation.
	ETag string `json:"etag"`

	// Size is the object size in bytes.
	Size int64 `json:"size"`
}

type Store[T any, P any, ID comparable] interface {
	// Reader provides Get (retrieve by id).
	Reader[T, ID]
	// Lister provides List (paginated query by params).
	Lister[T, P]
	// Writer provides Create and Update.
	Writer[T, ID]
	// Deleter provides Delete (remove by id).
	Deleter[ID]
	// Exister provides Exists (existence check by id).
	Exister[ID]
}

type ToolSpec interface {
	// Name returns the display name (e.g., "golangci-lint").
	Name() string

	// Binary returns the executable name on PATH (e.g., "golangci-lint").
	Binary() string

	// InstallHint returns installation instructions.
	InstallHint() string

	// Cmd builds the full command: (executable, args) with prefix handling.
	// For tools with a prefix (e.g., "uv run ruff"), Cmd("check", ".")
	// returns ("uv", ["run", "ruff", "check", "."]).
	Cmd(args ...string) (exe string, cmdArgs []string)
}

type Tracer interface {
	// Start creates a new span and returns the updated context and span.
	Start(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)

	// Shutdown flushes and shuts down the tracer.
	Shutdown(ctx context.Context) error
}

type Transaction interface {
	// Commit commits the transaction.
	Commit() error

	// Rollback aborts the transaction.
	Rollback() error
}

type TransactionManager interface {
	// Begin starts a new transaction and returns a context with the transaction attached.
	Begin(ctx context.Context) (context.Context, Transaction, error)

	// WithTransaction executes fn within a transaction, automatically committing
	// on success or rolling back on error.
	WithTransaction(ctx context.Context, fn func(ctx context.Context) error) error
}

type Updater[T any, ID comparable] interface {
	// Update modifies an existing entity identified by id.
	Update(ctx context.Context, id ID, entity *T) (*T, error)
}

type Validatable interface {
	// Validate reports whether the DTO satisfies its field + cross-field rules, returning the
	// first violation as a coded (CodeInvalidInput) error, or nil when every rule is satisfied.
	Validate() error
}

type Worker interface {
	// Work executes a job with the given arguments.
	Work(args map[string]interface{}) error
}

type WorkerRegistry interface {
	// Register associates a worker with a job kind.
	Register(kind string, worker Worker)

	// Get retrieves the worker registered for the given kind.
	Get(kind string) (Worker, bool)
}

type Workflow[In any, Out any] interface {
	// Execute orchestrates a multi-step business process.
	// Context is provided for cancellation and tracing.
	// Implementations may be stateful and typically depend on services, repos, and caches.
	Execute(ctx context.Context, input In) (Out, error)
}

type Writer[T any, ID comparable] interface {
	// Create persists a new entity and returns it with generated fields populated.
	Create(ctx context.Context, entity *T) (*T, error)

	// Update modifies an existing entity identified by id.
	Update(ctx context.Context, id ID, entity *T) (*T, error)
}