contracts

type Action string

type AtomicMovable interface {
	AtomicMove(ctx context.Context, src, dst string) error
}

type AuditEntry struct {
	ID         string
	Timestamp  time.Time
	Actor      string            // user ID, "system", or module ID
	Action     string            // e.g., "http.request", "module.registered", "media.requested"
	Resource   string            // e.g., "/api/movies", "admin-ui", "Inception"
	ResourceID string            // UUID of the affected resource, if applicable
	Details    map[string]string // arbitrary context — MUST NOT contain credentials or PII
	TraceID    string
	NodeID     string
	// PrevEntryHash is the SHA-256 hash of the chronologically previous audit entry.
	// This forms a tamper-evident hash chain. Zero value for the first entry in a log.
	PrevEntryHash string
	// Signature is an optional HMAC-SHA256 over the entry fields using a root key.
	// Enables verification that the entry was produced by an authorized audit logger.
	// Empty if the audit logger does not support cryptographic signing.
	Signature string
}

type AuditFilter struct {
	Actor    string
	Action   string
	Resource string
	From     time.Time
	To       time.Time
	TraceID  string
	// VerifyChain, when true, instructs Query to validate the hash chain
	// of returned entries and exclude or flag entries with broken links.
	VerifyChain bool
}

type AuditLogger interface {
	// Log records an audit entry.
	//
	// SECURITY: Details MUST NOT contain credentials, tokens, or PII.
	// The caller is responsible for redacting sensitive data before
	// calling Log. Use DataRedactionProvider if the details map is
	// built from untrusted input.
	Log(ctx context.Context, entry AuditEntry) error

	// Query returns entries matching the filter.
	Query(ctx context.Context, filter AuditFilter) ([]AuditEntry, error)

	// Export writes all entries in the given format (json, csv).
	Export(ctx context.Context, format string) (io.ReadCloser, error)

	// VerifyChainIntegrity performs a standalone integrity check on the
	// audit log hash chain in the given time range. Unlike Query with
	// VerifyChain=true, this method does not return entry data — it only
	// returns the verification result. This enables independent integrity
	// audits without exposing audit content to the verifier.
	//
	// If the provider does not support hash chains, this method returns
	// a result with Valid=true and TotalEntries=0 (no chain to verify).
	VerifyChainIntegrity(ctx context.Context, from, to time.Time) (ChainVerificationResult, error)

	// VerifyAll performs a full integrity check across all surviving
	// rotated audit log files and the current active file, verifying
	// the hash chain and HMAC signatures across file boundaries.
	//
	// Entries in the deleted oldest rotated file (if any) are reported
	// in UnverifiableCount. The active file is snapshotted at call time;
	// entries written concurrently are not included.
	VerifyAll(ctx context.Context) (ChainVerificationResult, error)
}

type AuthProvider interface {
	// Authenticate verifies credentials and returns a session if valid.
	// The returned Session.Token is the bearer token for subsequent
	// Validate calls.
	Authenticate(ctx context.Context, credentials Credentials) (Session, error)

	// Validate checks whether a token is still valid and returns the
	// associated session. Returns an error if the token is expired,
	// revoked, or malformed.
	//
	// SECURITY: The token parameter MUST NOT be logged. Use a
	// cryptographically safe prefix (first 8 chars of SHA-256) for
	// audit trail references.
	Validate(ctx context.Context, token string) (Session, error)

	// Revoke invalidates a token so it can no longer be used for
	// Validate calls. Already-established sessions are not affected
	// until their next Validate.
	Revoke(ctx context.Context, token string) error
}

type Authorizer interface {
	// Can performs a permission check using a flat (action, resource) pair.
	//
	// SECURITY: The session parameter contains a raw token. Authorizer
	// implementations MUST NOT log or store the full Session struct.
	// Use session.Safe() if identity information is needed for audit.
	Can(ctx context.Context, session Session, action string, resource string) (bool, error)
}

type BackupInfo struct {
	ID        string
	Timestamp time.Time
	Size      int64
	Modules   []string // module IDs included in the backup
}

type BackupProvider interface {
	// CreateBackup captures state from all registered Backupable modules.
	CreateBackup(ctx context.Context) (BackupInfo, error)
	// Restore restores state from a previous backup.
	Restore(ctx context.Context, backupID string) error
	// ListBackups returns all available backups.
	ListBackups(ctx context.Context) ([]BackupInfo, error)
	// DeleteBackup removes a stored backup.
	DeleteBackup(ctx context.Context, backupID string) error
}

type Backupable interface {
	// ExportState returns serialized state for backup.
	ExportState(ctx context.Context) ([]byte, error)
	// ImportState restores state from a backup.
	ImportState(ctx context.Context, data []byte) error
}

type CacheLayer interface {
	// Get returns cached data for the given key. The bool indicates a cache hit.
	Get(ctx context.Context, key string) ([]byte, bool)
	// Set caches data for the given key.
	Set(ctx context.Context, key string, data []byte) error
	// Invalidate removes all cached entries whose key has the given prefix.
	Invalidate(ctx context.Context, prefix string) error
}

type CacheProvider interface {
	// Get retrieves a value by key. Returns nil, nil if the key does not exist.
	Get(ctx context.Context, key string) ([]byte, error)
	// Set stores a value with an optional TTL. Zero TTL means no expiration.
	Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
	// Delete removes one or more keys.
	Delete(ctx context.Context, keys ...string) error
	// Exists checks whether a key exists.
	Exists(ctx context.Context, key string) (bool, error)
	// Incr atomically increments an integer key by delta and returns the new value.
	Incr(ctx context.Context, key string, delta int64) (int64, error)
	// CompareAndSwap atomically replaces oldValue with newValue at key.
	// Returns true if the swap succeeded (key held oldValue), false otherwise.
	// A nil oldValue matches a non-existent key.
	CompareAndSwap(ctx context.Context, key string, oldValue, newValue []byte) (bool, error)
	// Lock acquires a distributed lock on a key. Returns a Lock handle.
	// If the key is already locked, returns an error immediately (non-blocking).
	Lock(ctx context.Context, key string, ttl time.Duration) (LockHandle, error)
	// Publish sends a message on a pub/sub channel.
	Publish(ctx context.Context, channel string, msg []byte) error
	// Subscribe returns a channel that receives messages published on the given channel.
	Subscribe(ctx context.Context, channel string) (<-chan []byte, error)
}

type CallPolicyProvider interface {
	// AllowCall returns (true, nil) if caller is permitted to invoke method on target.
	// Returns (false, nil) if access is denied, or (false, error) if the policy engine
	// encountered an error (transient failure, configuration issue, etc.).
	AllowCall(ctx context.Context, callerModuleID, targetModuleID, method string) (bool, error)
}

type ChainVerificationResult struct {
	// Valid is true if the entire chain is intact with no broken links.
	Valid bool
	// TotalEntries is the number of entries in the verified range.
	TotalEntries int
	// UnverifiableCount is the number of entries that existed in the oldest
	// rotated file which was deleted before verification. These entries
	// cannot be verified and are not counted in TotalEntries.
	UnverifiableCount int
	// BrokenLinks is the list of entry IDs where the PrevEntryHash does
	// not match the computed hash of the previous entry.
	BrokenLinks []string
	// FirstBrokenAt is the timestamp of the first detected break, or
	// the zero time if no breaks were found.
	FirstBrokenAt time.Time
}

type CircuitBreaker interface {
	// Execute runs fn within the circuit identified by key.
	// If the circuit is open, returns ErrCircuitOpen immediately.
	// If fn returns an error, the failure is recorded against the circuit.
	Execute(ctx context.Context, key string, fn func(context.Context) error) error

	// State returns the current state of the circuit identified by key.
	State(key string) CircuitState
}

type CircuitState string

type Cluster interface {
	// Start joins or forms a cluster. If no seed nodes are reachable,
	// the node starts a new single-node cluster.
	Start(ctx context.Context) error

	// Stop gracefully leaves the cluster.
	Stop(ctx context.Context) error

	// Members returns all current cluster members.
	Members() []NodeInfo

	// Leader returns the current leader, or nil if unknown.
	Leader() *NodeInfo

	// LocalNode returns information about this node.
	LocalNode() NodeInfo

	// Events returns a channel that emits cluster membership changes.
	Events() <-chan ClusterEvent

	// Health checks whether the cluster is operational.
	Health(ctx context.Context) error

	// FindNodesByLabel returns all nodes with the given label value.
	FindNodesByLabel(ctx context.Context, label, value string) []NodeInfo

	// FindNodesByModule returns all nodes running the given module.
	FindNodesByModule(ctx context.Context, moduleID string) []NodeInfo
}

type ClusterEvent struct {
	Type     ClusterEventType
	Node     NodeInfo
	LeaderID string
}

type ClusterEventType string

type ConfigWatcher interface {
	// OnChange registers a handler that fires when modules matching the
	// given capability string are added or removed. Returns a cancel
	// function to stop watching. The handler receives no arguments —
	// the module is expected to re-query the registry for current state.
	OnChange(ctx context.Context, capability string, handler func()) (cancel func())
}

type ContractDeclaration struct {
	Repo      string // Go module path of the contract package
	Version   string // semantic version tag (e.g. "v1.0.0")
	Interface string // Go interface name the module implements (e.g. "Downloader")
}

type Counter interface {
	Inc()
	Add(delta float64)
}

type CredentialType string

type Credentials struct {
	Type string
	Data []byte
}

type DataRedactionProvider interface {
	// Redact returns a new map with sensitive values replaced according
	// to the given rules. The input map is not modified. Rules are
	// provider-specific identifiers; the provider silently ignores
	// rules it doesn't recognize.
	Redact(ctx context.Context, data map[string]any, rules []string) (map[string]any, error)
}

type DatabaseParams struct {
	// Driver is the database driver name (e.g., "postgres", "sqlite3").
	Driver string
	// Host is the database server address (host:port or socket path).
	Host string
	// Database is the database name.
	Database string
	// User is the database username.
	User string
	// Password is the database password. Leave empty for passwordless auth.
	//
	// SECURITY: Never log this field. Fetch the password from
	// SecretsProvider at connection time rather than storing it in
	// application state.
	Password string
	// Extra carries driver-specific connection parameters (e.g., sslmode,
	// connect_timeout). These are appended to the DSN after the core params.
	// Keys and values in Extra must not contain credentials.
	Extra map[string]string
}

type DatabaseProvider interface {
	// Open initializes the database connection using separated connection
	// parameters. This isolates credentials from connection metadata,
	// reducing the risk of accidental credential exposure.
	//
	// Implementations SHOULD return ErrDatabaseCredentialExposure if
	// the caller attempts to embed credentials in Extra.
	Open(ctx context.Context, params DatabaseParams) error

	// Close gracefully shuts down the database connection.
	Close(ctx context.Context) error
	// Health checks whether the database is reachable.
	Health(ctx context.Context) error
	// Exec runs a statement that modifies data (INSERT, UPDATE, DELETE, DDL).
	//
	// SECURITY: Callers MUST use parameterized queries. Never concatenate
	// user input into the query string. The args ...any parameter supports
	// standard SQL placeholders ($1, ?, :name). Consider using
	// InputValidator with "sql:<param-count>" schema for additional
	// injection protection.
	Exec(ctx context.Context, query string, args ...any) (int64, error)
	// Query runs a read query and returns a row iterator.
	//
	// SECURITY: Same parameterization requirement as Exec. All user
	// input MUST be passed via args, never interpolated into query.
	Query(ctx context.Context, query string, args ...any) (Rows, error)
	// Transaction runs fn inside a database transaction, committing on success and rolling back on error.
	Transaction(ctx context.Context, fn func(Tx) error) error
	// Migrate applies ordered schema migrations. Implementations track which migrations
	// have already been applied and skip those.
	//
	// SECURITY: Migration SQL (Up/Down strings) is trusted schema code.
	// Implementations SHOULD verify migration content against a known
	// checksum or signature before execution when operating in production.
	Migrate(ctx context.Context, migrations []Migration) error

	// Rollback reverts schema migrations down to the given target version
	// by applying Down SQL in reverse version order. targetVersion of 0
	// rolls back all migrations (empty schema). Returns nil if no rollback
	// is needed (current version <= targetVersion). Returns
	// ErrMigrationTargetNotFound if targetVersion does not exist in the
	// migrations list. Returns ErrRollbackNotSupported if the provider
	// does not implement rollback.
	//
	// Implementations MUST apply Down SQL within transactions and track
	// the current schema version in their migrations tracking table.
	// They MUST reject rollback past version 0 (dropping below baseline).
	Rollback(ctx context.Context, targetVersion int) error
}

type DeadLetterEntry struct {
	Event       Event
	HandlerName string
	Error       string
	FailedAt    time.Time
	RetryCount  int
}

type DeadLetterProvider interface {
	// Store records a failed event delivery. Called by the event bus
	// or by modules that want explicit dead-letter handling.
	Store(ctx context.Context, event Event, handlerName string, err error) error

	// Replay returns failed events for the given handler since the given time.
	// Sorted by FailedAt ascending.
	Replay(ctx context.Context, handlerName string, since time.Time) ([]DeadLetterEntry, error)

	// Discard removes a failed event from the dead letter store after
	// the issue has been resolved.
	Discard(ctx context.Context, eventID string) error
}

type DistributedLockHandle interface {
	// Unlock releases the lock. Safe to call multiple times.
	Unlock(ctx context.Context) error

	// Renew extends the lock's TTL without releasing and re-acquiring.
	// Useful for long-running operations where the initial TTL would expire
	// before completion. Returns ErrLockHeld if the lock was lost (e.g.,
	// network partition caused the backend to expire it).
	Renew(ctx context.Context, ttl time.Duration) error
}

type DistributedLockProvider interface {
	// Acquire attempts to acquire a lock for the given key with a TTL.
	// Returns (nil, ErrLockHeld) if the key is already locked.
	// Returns (nil, ctx.Err()) if the context is cancelled before acquisition.
	// The returned handle must be Unlock()ed when the critical section completes.
	Acquire(ctx context.Context, key string, ttl time.Duration) (DistributedLockHandle, error)
}

type EncryptionProvider interface {
	// Encrypt encrypts plaintext and returns self-describing ciphertext.
	// The returned bytes include key version metadata so Decrypt can
	// identify the correct key even after rotation.
	Encrypt(ctx context.Context, plaintext []byte) ([]byte, error)

	// Decrypt decrypts ciphertext that was produced by Encrypt.
	// The provider reads key metadata from the ciphertext to select
	// the correct decryption key, including keys from previous rotations.
	Decrypt(ctx context.Context, ciphertext []byte) ([]byte, error)

	// RotateKey initiates key rotation. After rotation, new Encrypt calls
	// use the new key. Old keys remain available for Decrypt indefinitely —
	// previously encrypted data does not need re-encryption.
	//
	// SECURITY: Implementations that do NOT support rotation (static-key
	// implementations) MUST return an error from this method. Production
	// deployments SHOULD use a provider that supports rotation.
	RotateKey(ctx context.Context) error

	// Available reports whether encryption is configured and operational.
	// Returns false if no provider is registered or the provider is in a
	// degraded state. The fabric SHOULD use this to enforce encryption
	// requirements at startup.
	Available() bool
}

type Event struct {
	ID        string
	Type      string
	Source    string
	TraceID   string
	Payload   []byte
	Metadata  map[string]string
	Timestamp time.Time
}

type EventBus interface {
	Publish(ctx context.Context, event Event) error

	// Subscribe registers a handler for the given event type.
	// Use "*" to subscribe to all events.
	// Returns a cancel function that removes the subscription when called.
	// The cancel function is safe to call multiple times.
	Subscribe(ctx context.Context, eventType string, handler EventHandler) (cancel func(), err error)

	// Request publishes an event and waits for a reply on ReplyEventType(event.Type).
	Request(ctx context.Context, event Event, timeout time.Duration) (Event, error)

	// SubscribeModule registers a handler tagged with a module identifier.
	// Returns a cancel function that removes this subscription when called.
	// Use UnsubscribeAll for bulk removal of all subscriptions owned by a module.
	SubscribeModule(ctx context.Context, moduleID, eventType string, handler EventHandler) (cancel func(), err error)

	// UnsubscribeAll removes all subscriptions tagged with the given module ID.
	// If moduleID is empty, this is a no-op. Used by module lifecycle management
	// during shutdown to prevent handlers from receiving events after the
	// module has stopped.
	UnsubscribeAll(ctx context.Context, moduleID string) error
}

type EventHandler func(ctx context.Context, event Event) error

type EventStore interface {
	// Append writes events to a stream and returns their assigned sequence
	// numbers. Events in a single Append call are atomic — either all
	// are written or none are. Returns the starting sequence number for
	// the batch and an error if the write fails.
	//
	// The first event in a new stream gets sequence 1.
	Append(ctx context.Context, stream string, events []Event) (firstSequence int64, err error)

	// Read returns events from a stream starting at fromSequence (inclusive).
	// limit caps the number of events returned. Pass 0 for no limit
	// (provider default). Returns events in ascending sequence order.
	// Returns an empty slice if fromSequence is beyond the stream end.
	Read(ctx context.Context, stream string, fromSequence int64, limit int) ([]EventStoreEntry, error)

	// Subscribe returns a channel that receives new events appended to
	// the stream starting from fromSequence. The channel closes when ctx
	// is cancelled. Events are delivered in sequence order.
	//
	// To catch up on existing events before live ones, call Read first
	// to get historical events, then Subscribe from the last sequence + 1.
	Subscribe(ctx context.Context, stream string, fromSequence int64) (<-chan EventStoreEntry, error)

	// Streams returns the names of all known streams.
	Streams(ctx context.Context) ([]string, error)
}

type EventStoreEntry struct {
	// Stream is the logical partition this event belongs to.
	Stream string

	// Sequence is the monotonically increasing position within the stream.
	// The first event in a stream has sequence 1.
	Sequence int64

	// Event is the stored event with type, source, payload, and metadata.
	Event Event

	// StoredAt is when the event was appended to the store.
	StoredAt time.Time

	// Extra carries provider-specific extensions (e.g., partition info,
	// checksum, storage tier).
	Extra map[string]any
}

type Executor interface {
	CanHandle(taskType string) bool
	Execute(ctx context.Context, task WorkerTask) (result []byte, err error)
}

type FeatureFlagProvider interface {
	// IsEnabled checks whether a feature flag is enabled for the caller
	// in the given context. The context carries identity for percentage-based
	// rollouts and targeting rules. defaultValue is returned when no provider
	// is registered or the flag is not defined.
	IsEnabled(ctx context.Context, flag string, defaultValue bool) bool

	// GetVariant returns the assigned variant for a multivariate flag.
	// Useful for A/B testing where a flag has more than two states.
	// defaultValue is returned when no provider is registered or the
	// flag is not defined.
	GetVariant(ctx context.Context, flag string, defaultValue string) string
}

type Gauge interface {
	Set(value float64)
	Inc()
	Dec()
	Add(delta float64)
}

type Hardlinkable interface {
	Hardlink(ctx context.Context, src, dst string) error
}

type HealthMonitor interface {
	// StartMonitoring begins periodic health checking. The monitor calls Health()
	// on every registered module at the configured interval and publishes
	// events on the bus for any degraded modules.
	StartMonitoring(ctx context.Context, reg Registry, bus EventBus) error

	// Stop gracefully stops the health monitor.
	Stop(ctx context.Context) error
}

type Histogram interface {
	Observe(value float64)
}

type IdempotencyProvider interface {
	// Store records that a key has been processed and caches the result.
	// Returns (true, nil) if the key was new — this is the first occurrence.
	// Returns (false, nil) if the key was already stored — this is a duplicate.
	// The result is cached for ttl; after expiry the key may be evicted.
	Store(ctx context.Context, key string, result []byte, ttl time.Duration) (bool, error)

	// Exists checks whether a key has been previously stored and not yet expired.
	// Returns true if the key exists, false otherwise.
	Exists(ctx context.Context, key string) (bool, error)

	// Result retrieves the cached result for a previously stored key.
	// Returns (nil, nil) if the key does not exist or has expired.
	// This allows a duplicate request to receive the same response
	// as the original without re-executing the operation.
	Result(ctx context.Context, key string) ([]byte, error)
}

type Identity struct {
	// ID is the unique identifier for this caller (user ID, service account ID).
	ID string

	// Kind describes the type of identity (e.g., "user", "service", "api-key").
	Kind string

	// Roles are the authorization roles assigned to this identity.
	Roles []string

	// Claims carries provider-specific claims extracted from the auth token.
	// For JWT this is the decoded payload. For API keys this may be scopes.
	//
	// SECURITY: May contain sensitive data. Redact before logging.
	Claims map[string]any

	// Extra carries provider-specific extensions that consumers can interpret.
	//
	// SECURITY: May contain sensitive data. Redact before logging.
	Extra map[string]any
}

type IdentityProvider interface {
	// ExtractIdentity extracts the caller identity from the given context.
	// Returns (nil, nil) if no identity is present (unauthenticated request).
	// Returns an error only if identity extraction itself fails (e.g., invalid
	// token format), not if the request is simply unauthenticated.
	ExtractIdentity(ctx context.Context) (*Identity, error)
}

type InputValidator interface {
	// Validate checks the given data against the named schema and returns
	// a result indicating pass/fail plus any sanitized output.
	//
	// The schema parameter follows the conventions above. If the schema is
	// not recognised, implementations should return a ValidationResult with
	// Valid=false and an error entry explaining the unknown schema, rather
	// than returning an error — this allows callers to fall back gracefully.
	//
	// SECURITY: The schema string MUST be validated before use (see type docs).
	Validate(ctx context.Context, data []byte, schema string) (ValidationResult, error)

	// SupportedSchemas returns the list of schema identifiers this validator
	// can handle. Used for capability discovery so callers can determine at
	// registration time whether a validator meets their needs.
	SupportedSchemas() []string
}

type LBStrategy interface {
	// Pick returns the index of the selected candidate from candidates.
	// candidates is guaranteed to have at least one entry.
	// Returns ErrNoCandidates if candidates is empty.
	Pick(ctx context.Context, candidates []NodeInfo) (int, error)
}

type LeaderChangedPayload struct {
	PreviousLeader string `json:"previous_leader"`
	NewLeader      string `json:"new_leader"`
}

type LockHandle interface {
	// Unlock releases the lock.
	Unlock(ctx context.Context) error
}

type LogLevel string

type MeshHandler interface {
	// HandleCall processes a cross-module method invocation.
	// method is an arbitrary string the caller and handler agree on.
	// payload is the JSON-encoded request body.
	// Returns the JSON-encoded response or an error.
	HandleCall(ctx context.Context, method string, payload []byte) ([]byte, error)
}

type MetricsProvider interface {
	// Counter creates or returns a counter with the given name and labels.
	Counter(name string, labels map[string]string) Counter
	// Gauge creates or returns a gauge with the given name and labels.
	Gauge(name string, labels map[string]string) Gauge
	// Histogram creates or returns a histogram with the given name, labels, and buckets.
	Histogram(name string, labels map[string]string, buckets []float64) Histogram
}

type Migration struct {
	Version int
	Name    string
	Up      string // SQL to apply
	// Down is SQL to revert the migration. Used by Rollback to undo
	// schema changes in reverse version order.
	Down string
}

type Module interface {
	Info() ModuleInfo
	Init(ctx context.Context) error
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
	Health(ctx context.Context) error
}

type ModuleDegradedPayload struct {
	ModuleID string `json:"module_id"`
	Error    string `json:"error"`
}

type ModuleEntry struct {
	Info   ModuleInfo
	State  ModuleState
	Module Module
}

type ModuleInfo struct {
	ID           string
	Name         string
	Version      string
	Roles        []string // module-defined role strings; core imposes no taxonomy
	Description  string
	Author       string
	Capabilities []string              // granular capability strings for routing/discovery
	Contracts    []ContractDeclaration // typed contracts this module implements
	DependsOn    []string              // module IDs that must be initialized before this module starts. Cycles detected by Registry.StartupOrder().
	// MinCoreVersion is the minimum core version required by this module.
	// Uses SemVer (e.g., "1.2.0"). Empty means compatible with any version.
	// Core rejects modules whose MinCoreVersion is greater than the running
	// core version or targets a different major version.
	MinCoreVersion string
	// HTTPAddr is the address where this module serves HTTP, if any.
	// Example: ":8085" or "0.0.0.0:9200". Leave empty if the module does not
	// expose HTTP. Other modules discover this via ModuleEntry.Info.HTTPAddr
	// after a successful FindByCapability or Resolve call.
	HTTPAddr string
}

type ModuleKind string

type ModuleMeshClient interface {
	// Call invokes a method on the target module. If the target is registered
	// locally, the call is dispatched in-process with zero network overhead.
	// If the target is on a remote node, the call goes over gRPC.
	Call(ctx context.Context, targetModule, method string, payload []byte) ([]byte, error)

	// RegisterHandler registers a local module to receive incoming Call requests.
	// Only call this during module Start(). Modules that don't receive calls
	// don't need to register.
	RegisterHandler(moduleID string, handler MeshHandler)
}

type ModuleRegisteredPayload struct {
	ModuleID string `json:"module_id"`
	Version  string `json:"version"`
}

type ModuleState string

type ModuleUnregisteredPayload struct {
	ModuleID string `json:"module_id"`
}

type NodeInfo struct {
	ID        string
	GRPCAddr  string
	HTTPAddr  string
	Labels    map[string]string
	ModuleIDs []string
	// ModuleHealth maps module ID to health status.
	// Empty string means healthy. Non-empty is the last health check error.
	ModuleHealth map[string]string
}

type NodeJoinedPayload struct {
	NodeID   string `json:"node_id"`
	GRPCAddr string `json:"grpc_addr"`
	HTTPAddr string `json:"http_addr"`
}

type NodeLeftPayload struct {
	NodeID string `json:"node_id"`
}

type ObjectInfo struct {
	Key          string
	Size         int64
	ContentType  string
	ETag         string
	LastModified time.Time
	Metadata     map[string]string
}

type Permission string

type PublishPolicyProvider interface {
	// CanPublish returns (true, nil) if the caller is permitted to publish
	// events of the given type. Returns (false, nil) if publishing is denied.
	CanPublish(ctx context.Context, callerID, eventType string) (bool, error)
}

type RateLimiterProvider interface {
	// Allow checks whether a request from the given key (typically IP) is allowed.
	// Returns true if the request should proceed, false if it should be rate-limited.
	Allow(ctx context.Context, key string) bool

	// Enabled returns whether rate limiting is active.
	Enabled() bool
}

type RedactingLogger interface {
	StructuredLogger

	// IsRedacting reports whether this logger automatically applies
	// redaction to all fields before writing to sinks.
	IsRedacting() bool
}

type Registry interface {
	FindByRole(role string) []ModuleEntry
	FindByCapability(cap string) []ModuleEntry
	SupportsCapability(moduleID, cap string) bool
	Resolve(id string) (ModuleEntry, error)
	ListAll() []ModuleEntry

	// StartupOrder returns module IDs in dependency-respecting order.
	// Modules listed in DependsOn appear before the module that depends on them.
	// Returns an error if a dependency cycle is detected.
	StartupOrder() ([]string, error)

	// DependencyGraph returns modules that list the given ID in their DependsOn.
	// Useful for understanding the impact of stopping or removing a module.
	DependencyGraph(id string) ([]string, error)
}

type ResourceAuthorizer interface {
	Authorizer

	// CanWithResource performs a permission check with resource context.
	// The resource descriptor enables hierarchical checks, ABAC policies,
	// and resource-ownership gating. When ResourceDescriptor.ID is empty,
	// the check is scoped to the resource type.
	CanWithResource(ctx context.Context, session Session, action Action, resource ResourceDescriptor) (bool, error)
}

type ResourceDescriptor struct {
	// Type is the resource kind, e.g. "media", "storage", "module".
	Type string
	// ID is the resource identifier, e.g. a UUID or key path.
	// Empty means the check is at the resource-type level.
	ID string
	// Attributes carries additional resource properties that
	// policy engines can use for ABAC decisions (owner, labels, tier).
	// MUST NOT contain credentials or PII.
	Attributes map[string]string
}

type ResourcePublishPolicyProvider interface {
	PublishPolicyProvider

	// CanPublishEvent performs event-level authorization with access to
	// the full event payload. This enables resource-level checks beyond
	// the type-level check in CanPublish.
	CanPublishEvent(ctx context.Context, callerID string, event Event) (bool, error)
}

type RetryPolicy struct {
	// MaxAttempts is the maximum number of attempts, including the first.
	// A value of 0 means the provider's default (typically 3).
	MaxAttempts int

	// InitialDelay is the delay before the first retry.
	// A value of 0 means the provider's default (typically 100ms).
	InitialDelay time.Duration

	// MaxDelay is the maximum delay between retries. The backoff caps at this.
	// A value of 0 means no cap (provider default).
	MaxDelay time.Duration

	// BackoffFactor is multiplied against the delay on each retry.
	// Typical values: 2.0 (exponential), 1.0 (fixed delay).
	// A value of 0 means the provider's default (typically 2.0).
	BackoffFactor float64

	// Jitter, when true, adds random jitter to the delay to avoid thundering herd.
	Jitter bool

	// Extra carries provider-specific extensions.
	Extra map[string]any
}

type RetryProvider interface {
	// Execute runs fn with retry semantics based on the given policy.
	// Returns nil if fn succeeds on any attempt. Returns the last error
	// if all attempts are exhausted. The context is passed to each attempt;
	// if ctx is cancelled, retries stop immediately.
	Execute(ctx context.Context, policy RetryPolicy, fn func(ctx context.Context) error) error
}

type Rows interface {
	Next() bool
	Scan(dest ...any) error
	Close() error
}

type Scheduler interface {
	Schedule(ctx context.Context, task SchedulerTask) (string, error)
	Cancel(ctx context.Context, taskID string) error
	Status(ctx context.Context, taskID string) (SchedulerTaskStatus, error)
	// List returns all scheduled tasks matching the filter. Pass nil to list all.
	List(ctx context.Context, filter *SchedulerTaskFilter) ([]SchedulerTask, error)
}

type SchedulerTask struct {
	ID       string
	Name     string
	CronExpr string
	Payload  []byte
	Timeout  time.Duration
	Meta     map[string]any
}

type SchedulerTaskFilter struct {
	Status SchedulerTaskStatus
	Name   string // substring match on task name; empty matches all
}

type SchedulerTaskStatus string

type SecretsProvider interface {
	// Get retrieves a secret by key. Returns an error if not found.
	Get(ctx context.Context, key string) (string, error)
	// Set stores a secret. Implementations may be read-only (e.g., env-backed)
	// and return an error for Set calls.
	Set(ctx context.Context, key, value string) error
	// Delete removes a secret. May not be supported by all backends.
	Delete(ctx context.Context, key string) error
	// List returns all known keys. Values are NOT included — only key names.
	List(ctx context.Context) ([]string, error)
}

type Seekable interface {
	Seek(ctx context.Context, key string, offset int64) (int64, error)
}

type SerializationProvider interface {
	// Marshal serializes v to bytes using the specified content type.
	// Common content types: "application/json", "application/x-protobuf",
	// "application/msgpack".
	Marshal(contentType string, v any) ([]byte, error)

	// Unmarshal deserializes data into v using the specified content type.
	// v must be a pointer to a concrete target type.
	//
	// SECURITY: The content type and data originate from untrusted sources
	// (the wire or another module). Implementations MUST validate the
	// content type against a safelist before deserializing.
	Unmarshal(contentType string, data []byte, v any) error

	// SupportedTypes returns the content types this provider can handle.
	// Callers can negotiate format by intersecting their needs with this list.
	//
	// SECURITY: The returned list MUST only include types that have been
	// vetted for safe deserialization. See SafeSerializationTypes above.
	SupportedTypes() []string
}

type Session struct {
	UserID      string
	Username    string
	Roles       []string
	Permissions []string
	Token       string // SECURITY: zero before logging or serializing
}

type SettingDef struct {
	Key         string // env var or config key, e.g. "MUXCORE_JACKETT_URL"
	Label       string // human-readable label, e.g. "Jackett Server URL"
	Type        SettingType
	Default     string // default value as a string
	Description string // help text
	Required    bool
	Options     []string // for SettingTypeSelect: allowed values
	Group       string   // settings group, e.g. "Connection", "Downloads"
}

type SettingType string

type SettingsProvider interface {
	Settings() []SettingDef
}

type Span interface {
	// SetAttribute records a key-value pair on the span. Attributes appear
	// in trace visualizations and can be searched.
	SetAttribute(key string, value string)

	// SetStatus records the outcome of the span. Call before End().
	SetStatus(code SpanStatusCode, description string)

	// End marks the span as complete and sends it to the tracing backend.
	End()
}

type SpanStatusCode int

type SpoolResolver interface {
	// ResolveTag fetches and parses a tag definition from the given spool URL.
	// The context carries deadlines and cancellation for the network request.
	ResolveTag(ctx context.Context, spoolURL, tagName string) (*TagDefinition, error)
}

type StepCompletedPayload struct {
	RunID    string         `json:"run_id"`
	StepName string         `json:"step_name"`
	Duration string         `json:"duration"`
	Output   map[string]any `json:"output"`
}

type StepFailedPayload struct {
	RunID    string `json:"run_id"`
	StepName string `json:"step_name"`
	Attempt  int    `json:"attempt"`
	MaxRetry int    `json:"max_retry"`
	Error    string `json:"error"`
}

type StepHandler struct {
	// Kind determines how Ref is interpreted.
	Kind StepHandlerKind
	// Ref is a module ID (Kind=StepHandlerModule) or capability string
	// (Kind=StepHandlerCapability).
	Ref string
}

type StepHandlerKind string

type StepResult struct {
	StepName   string
	Status     string // "success", "failed", "skipped"
	StartedAt  time.Time
	EndedAt    time.Time
	Attempt    int
	MaxRetries int
	Output     map[string]any // step output data passed to subsequent steps
	Error      string
}

type StepStartedPayload struct {
	RunID    string `json:"run_id"`
	StepName string `json:"step_name"`
	Handler  string `json:"handler"`
	Attempt  int    `json:"attempt"`
}

type StorageEvent struct {
	Type StorageEventType
	Key  string
}

type StorageEventType string

type StorageOrchestrator interface {
	Get(ctx context.Context, key string) (io.ReadCloser, error)
	Put(ctx context.Context, key string, data io.Reader, size int64) error
	Delete(ctx context.Context, key string) error
	Move(ctx context.Context, src, dst string) error
	Exists(ctx context.Context, key string) (bool, error)
	Stat(ctx context.Context, key string) (ObjectInfo, error)
	List(ctx context.Context, prefix string) ([]ObjectInfo, error)
	// Stream reads a byte range from a storage object. Uses provider-side
	// streaming when the routed provider implements Streamable; otherwise
	// falls back to a full Get with client-side slicing.
	Stream(ctx context.Context, key string, offset, length int64) (io.ReadCloser, error)
	// CapabilityCheck returns which capability interfaces the routed provider
	// supports for the given key (streamable, seekable, watchable, etc.).
	// Modules use this to negotiate behavior at runtime.
	CapabilityCheck(ctx context.Context, key string) ([]string, error)
}

type StorageProvider interface {
	Put(ctx context.Context, key string, data io.Reader, size int64) error
	Get(ctx context.Context, key string) (io.ReadCloser, error)
	Delete(ctx context.Context, key string) error
	Move(ctx context.Context, src, dst string) error
	Exists(ctx context.Context, key string) (bool, error)
	Stat(ctx context.Context, key string) (ObjectInfo, error)
	List(ctx context.Context, prefix string) ([]ObjectInfo, error)
}

type StorageTier string

type Streamable interface {
	Stream(ctx context.Context, key string, offset, length int64) (io.ReadCloser, error)
}

type StructuredLogger interface {
	// Debug logs at debug level with structured fields.
	// SECURITY: fields may contain sensitive data — redact before calling.
	Debug(ctx context.Context, msg string, fields map[string]any)

	// Info logs at info level with structured fields.
	// SECURITY: fields may contain sensitive data — redact before calling.
	Info(ctx context.Context, msg string, fields map[string]any)

	// Warn logs at warning level with structured fields.
	// SECURITY: fields may contain sensitive data — redact before calling.
	Warn(ctx context.Context, msg string, fields map[string]any)

	// Error logs at error level with structured fields.
	// SECURITY: fields may contain sensitive data — redact before calling.
	Error(ctx context.Context, msg string, fields map[string]any)

	// Level returns the configured minimum log level. Messages below this
	// level are silently dropped by the provider.
	Level() LogLevel
}

type TagDefinition struct {
	Name        string      `json:"name"`
	Description string      `json:"description"`
	Version     string      `json:"version"`
	Modules     []TagModule `json:"modules"`
}

type TagModule struct {
	Repo     string `json:"repo"`
	Version  string `json:"version"`
	Required bool   `json:"required"`
	Checksum string `json:"checksum,omitempty"`
	// InstanceID differentiates multiple copies of the same module on one
	// node. When set, the derived module ID becomes "{baseID}-{instanceID}"
	// instead of just "{baseID}". Allows running two identical modules
	// with different config (e.g. two torrent downloaders on different ports).
	InstanceID string `json:"instance_id,omitempty"`
	// Config is instance-specific configuration passed as environment
	// variables to the module binary. Each key is prefixed with MUXCORE_CFG_
	// and set as an env var during spawn.
	Config map[string]string `json:"config,omitempty"`
}

type TapestryCompletedPayload struct {
	RunID        string `json:"run_id"`
	DefinitionID string `json:"definition_id"`
	Duration     string `json:"duration"`
}

type TapestryDefinition struct {
	ID          string
	Name        string
	Description string
	Steps       []TapestryStep
	Version     string
	Meta        map[string]any
}

type TapestryFailedPayload struct {
	RunID        string `json:"run_id"`
	DefinitionID string `json:"definition_id"`
	StepName     string `json:"step_name"`
	Error        string `json:"error"`
}

type TapestryRun struct {
	ID           string
	DefinitionID string
	Status       TapestryStatus
	CurrentStep  string
	StepResults  []StepResult
	Input        map[string]any
	StartedAt    time.Time
	EndedAt      time.Time
	Error        string
	Meta         map[string]any
}

type TapestryRunFilter struct {
	Status       TapestryStatus
	DefinitionID string
}

type TapestryStartedPayload struct {
	RunID        string `json:"run_id"`
	DefinitionID string `json:"definition_id"`
}

type TapestryStatus string

type TapestryStep struct {
	Name         string
	Handler      StepHandler
	Retry        int // max retry attempts (0 = no retry)
	Timeout      time.Duration
	DependsOn    []string          // step names that must complete before this one
	InputMapping map[string]string // maps step output keys to this step's input keys
	Meta         map[string]any
}

type TierTransitionPayload struct {
	Key      string      `json:"key"`
	FromTier StorageTier `json:"from_tier"`
	ToTier   StorageTier `json:"to_tier"`
	Reason   string      `json:"reason"`
}

type TieredProvider interface {
	StorageProvider

	// Tier returns which tier this provider handles.
	Tier() StorageTier

	// Promote moves an object from this tier to a higher one.
	Promote(ctx context.Context, key string) error

	// Relegate moves an object from this tier to a lower one.
	Relegate(ctx context.Context, key string) error
}

type TracingProvider interface {
	// StartSpan begins a new span with the given name as a child of any
	// span in ctx. Returns the context carrying the new span and the span
	// itself. Call span.End() when the operation completes.
	StartSpan(ctx context.Context, name string) (context.Context, Span)
}

type Tx interface {
	// SECURITY: Same SQL parameterization requirements as DatabaseProvider.Exec/Query.
	Exec(ctx context.Context, query string, args ...any) (int64, error)
	Query(ctx context.Context, query string, args ...any) (Rows, error)
}

type ValidationResult struct {
	// Valid is true if the input passed all schema checks without errors.
	// When Valid is true, Sanitized holds the (possibly cleaned) data
	// that should be used in place of the original.
	Valid bool

	// Sanitized is the cleaned/sanitized version of the input data.
	// When Valid is true, callers should use this instead of the raw input.
	// When Valid is false, Sanitized may be nil or partial.
	Sanitized []byte

	// Errors is the list of validation failures. Empty when Valid is true.
	// Each entry describes a specific failure (e.g., "field email must
	// match pattern ^[^@]+@[^@]+$").
	Errors []string
}

type Watchable interface {
	Watch(ctx context.Context, prefix string) (<-chan StorageEvent, error)
}

type WorkerPool interface {
	Submit(ctx context.Context, task WorkerTask) (string, error)
	Status(ctx context.Context, taskID string) (WorkerTask, error)
	Cancel(ctx context.Context, taskID string) error
	List(ctx context.Context, filter *WorkerTaskFilter) ([]WorkerTask, error)

	// Reassign moves a task from a dead or unresponsive node to a new one.
	// If the task is already completed or cancelled, Reassign returns an error.
	// The new node should re-execute the task from scratch unless the executor
	// checks IdempotencyKey against an IdempotencyProvider.
	Reassign(ctx context.Context, taskID, newNode string) error
}

type WorkerTask struct {
	ID            string
	Type          string
	Payload       []byte
	AssignedNode  string
	Status        WorkerTaskStatus
	MaxRetries    int
	RetryCount    int
	Capabilities  []string
	CreatedAt     time.Time
	StartedAt     time.Time
	CompletedAt   time.Time
	LastHeartbeat time.Time
	Error         string
	Meta          map[string]any

	// IdempotencyKey is an optional key that executors use with
	// IdempotencyProvider to prevent duplicate execution. When a task
	// is reassigned after a node failure, the new executor checks this
	// key before re-executing. If empty, no idempotency guard is applied.
	IdempotencyKey string

	// HeartbeatInterval is how often the executor promises to call
	// Heartbeat() while processing this task. The worker pool reaper
	// uses this to detect stalled executors. If zero, the pool's
	// DefaultHeartbeatTimeout is used.
	HeartbeatInterval time.Duration
}

type WorkerTaskFilter struct {
	Status       WorkerTaskStatus
	Type         string
	AssignedNode string
}

type WorkerTaskStatus string

type WorkflowEngine interface {
	// RegisterDefinition stores a tapestry template for later execution.
	// definition.ID is the key used by Run.
	RegisterDefinition(ctx context.Context, definition TapestryDefinition) error

	// RemoveDefinition removes a previously registered definition.
	RemoveDefinition(ctx context.Context, definitionID string) error

	// GetDefinition returns a registered definition, or nil if not found.
	GetDefinition(ctx context.Context, definitionID string) (*TapestryDefinition, error)

	// ListDefinitions returns all registered definitions.
	ListDefinitions(ctx context.Context) ([]TapestryDefinition, error)

	// Run starts a tapestry execution. input carries the initial
	// data passed to the first step(s).
	Run(ctx context.Context, definitionID string, input map[string]any) (string, error)

	// Status returns the current state of a run.
	Status(ctx context.Context, runID string) (*TapestryRun, error)

	// Cancel stops a running tapestry. Already-completed steps
	// are not rolled back.
	Cancel(ctx context.Context, runID string) error

	// Pause suspends a running tapestry at the next step boundary.
	Pause(ctx context.Context, runID string) error

	// Resume continues a paused tapestry.
	Resume(ctx context.Context, runID string) error

	// ListRuns returns all runs, optionally filtered by status or definitionID.
	ListRuns(ctx context.Context, filter *TapestryRunFilter) ([]TapestryRun, error)
}