model

type Database interface {
	common.Service
	ORM() *gorm.DB
	DB() *sql.DB
	FromContext(ctx context.Context) *gorm.DB
	FromContextTimeout(ctx context.Context, timeout time.Duration) (*gorm.DB, context.CancelFunc)
	Cleanup(schema bool) error
	Reload() error
	// Transaction executes fn within a database transaction.
	Transaction(ctx context.Context, fn func(tctx context.Context) error, opts ...*sql.TxOptions) error
}

type MessageBus interface {
	common.Service

	// Register subscribes module to the bus topic. The module receives
	// messages via MessageHandler / RawMessageHandler if it implements them.
	Register(module common.Named)

	// SendMessage publishes a typed message on the bus topic. The sender
	// does not receive its own message.
	common.MessageSender

	// SendRawMessage publishes a message with an arbitrary payload on the bus
	// topic. The sender does not receive its own message.
	common.RawMessageSender

	// NewMessenger creates a Messenger subscribed to the bus topic under the
	// given (unique) name. Use this when you need raw channel access — e.g.,
	// to bridge the bus to a WebSocket, SSE stream, or custom dispatcher.
	// The caller is responsible for calling Close on the returned Messenger.
	NewMessenger(name string) (Messenger, error)

	// AttachWebSocket pumps messages between the Messenger and the WebSocket
	// connection: outbound (bus → ws) writes each message as JSON; inbound
	// (ws → bus) decodes JSON frames and republishes them. The call blocks
	// until the connection closes and then closes the Messenger.
	AttachWebSocket(messenger Messenger, ws *websocket.Conn)
}

type Messenger interface {
	common.Named

	// Ch returns the receive channel. The channel is closed by Close.
	Ch() <-chan entity.PubsubMessage

	// Send publishes a message on the bus topic with the Messenger as sender.
	// The Messenger does not receive its own message. Returns the error from
	// the underlying pubsub publish (e.g., network failure on a remote driver).
	Send(ctx context.Context, kind string, payload any) error

	// Close unsubscribes from the bus and closes the channel returned by Ch.
	Close()
}

type Planner interface {
	common.Service
	Add(todo *entity.Plan) error
	Cancel(id string) error
	Delete(id string, force bool) error
	GetResult(id string) (any, error)
	Stats(opts entity.PlannerStatsOptions) ([]*entity.PlannerStats, error)
}

type Pubsub interface {
	common.Service

	// Publish dispatches a message to every subscriber matching topic.
	// The from string identifies the publisher and is used to skip self-delivery
	// (subscribers registered under the same name do not receive their own
	// messages). ctx applies only to cross-instance delivery (network hop on
	// the redis/kafka drivers); local fan-out runs to completion regardless,
	// so partial delivery is possible if ctx is canceled mid-publish.
	Publish(ctx context.Context, from, topic, kind string, payload any) error

	// Subscribe registers a named subscriber for the topic and returns a
	// channel that receives every matching message, including sender metadata.
	// Topics are hierarchical: subscribing to "app" receives messages from
	// "app", "app/module", "app/module/component", etc.
	// Callers must call Unsubscribe to release the subscription.
	Subscribe(name, topic string) (<-chan entity.PubsubMessage, error)

	// Unsubscribe removes a subscriber from the topic and closes its channel.
	Unsubscribe(name, topic string) error
}

type Supervisor interface {
	common.Service
	Register(services ...common.Service)
	TopoSort() error
	Services() []common.Service
	Stats() ([]*entity.SupervisorStats, error)
	// Migrate() error
	InitService(ctx context.Context, name string) error
	StartService(name string) error
	StopService(name string, wait bool) error
	RestartService(ctx context.Context, name string) error
	Restart(ctx context.Context) error
}