storage

type AIBudget struct {
	VHost string `json:"vhost"`

	// Disabled is the kill switch: while it is on, no AI node or agent in
	// the vhost may call a model.
	Disabled bool `json:"disabled"`

	MonthlyTokens int64   `json:"monthly_tokens,omitempty"`
	MonthlyCost   float64 `json:"monthly_cost,omitempty"`
	// Currency labels the costs (for example USD). It is not converted.
	Currency string `json:"currency,omitempty"`

	// Prices are per million tokens. The model "*" prices every model the
	// list does not name; a cost limit needs it, so no call goes uncounted.
	Prices []AIModelPrice `json:"prices,omitempty"`

	Workflows []AIWorkflowCap `json:"workflows,omitempty"`

	UpdatedBy string    `json:"updated_by,omitempty"`
	UpdatedAt time.Time `json:"updated_at,omitzero"`
}

type AIBudgetStore interface {
	// GetAIBudget returns the vhost's budget, or ErrNotFound.
	GetAIBudget(ctx context.Context, vhost string) (AIBudget, error)
	// PutAIBudget creates or replaces the vhost's budget.
	PutAIBudget(ctx context.Context, b AIBudget) error
	// AddAIUsage adds d to a scope's usage for the period atomically, creating
	// the row on first use, and returns the totals after the addition.
	AddAIUsage(ctx context.Context, vhost, period, workflowID string, d AIUsageDelta) (AIUsage, error)
	// GetAIUsage returns a scope's usage for the period; zero when it has none.
	GetAIUsage(ctx context.Context, vhost, period, workflowID string) (AIUsage, error)
	// ListAIUsage returns every scope of the vhost with usage in the period,
	// the vhost's own row (no workflow) first and then by workflow id.
	ListAIUsage(ctx context.Context, vhost, period string) ([]AIUsage, error)
	// MarkAIUsageWarned records that kind's 80% alert went out for a scope
	// and period. It reports true to exactly one caller however many race,
	// replicas included, so the alert is raised once.
	MarkAIUsageWarned(ctx context.Context, vhost, period, workflowID, kind string) (bool, error)
	// DeleteAIBudgets removes the vhost's budget and all of its usage.
	DeleteAIBudgets(ctx context.Context, vhost string) error
}

type AIModelPrice struct {
	Model            string  `json:"model"`
	InputPerMillion  float64 `json:"input_per_million"`
	OutputPerMillion float64 `json:"output_per_million"`
}

type AIUsage struct {
	VHost        string `json:"vhost"`
	Period       string `json:"period"`
	WorkflowID   string `json:"workflow_id,omitempty"`
	Calls        int64  `json:"calls"`
	InputTokens  int64  `json:"input_tokens"`
	OutputTokens int64  `json:"output_tokens"`
	CostMicros   int64  `json:"cost_micros"`
	// TokensWarned and CostWarned record that the 80% alert went out.
	TokensWarned bool      `json:"tokens_warned,omitempty"`
	CostWarned   bool      `json:"cost_warned,omitempty"`
	UpdatedAt    time.Time `json:"updated_at,omitzero"`
}

type AIUsageDelta struct {
	InputTokens  int64
	OutputTokens int64
	CostMicros   int64
}

type AIWorkflowCap struct {
	WorkflowID    string  `json:"workflow_id"`
	MonthlyTokens int64   `json:"monthly_tokens,omitempty"`
	MonthlyCost   float64 `json:"monthly_cost,omitempty"`
}

type Approval struct {
	ID             string            `json:"id"`
	WorkflowID     string            `json:"workflow_id"`
	NodeID         string            `json:"node_id"`
	MessageID      string            `json:"message_id"`
	Payload        []byte            `json:"payload"`
	Metadata       map[string]string `json:"metadata"`
	Data           map[string]any    `json:"data"`
	FormDefinition map[string]any    `json:"form_definition,omitempty"`
	FormData       map[string]any    `json:"form_data,omitempty"`
	Status         string            `json:"status"` // pending, approved, rejected
	CreatedAt      time.Time         `json:"created_at"`
	ProcessedAt    *time.Time        `json:"processed_at,omitempty"`
	ProcessedBy    string            `json:"processed_by,omitempty"`
	Notes          string            `json:"notes,omitempty"`
}

type ApprovalFilter struct {
	CommonFilter
	WorkflowID string
	Status     string
	// VHosts, when not nil, limits the list to approvals raised by workflows
	// in these vhosts or in the shared default vhost ("", "default", "all"),
	// matching Handler.HasVHostAccess. Nil means no limit.
	VHosts []string
}

type AuditFilter struct {
	CommonFilter
	UserID     string     `json:"user_id"`
	EntityType string     `json:"entity_type"`
	EntityID   string     `json:"entity_id"`
	Action     string     `json:"action"`
	From       *time.Time `json:"from" omitzero:"true"`
	To         *time.Time `json:"to" omitzero:"true"`
}

type AuditLog struct {
	ID         string    `json:"id"`
	Timestamp  time.Time `json:"timestamp"`
	UserID     string    `json:"user_id"`
	Username   string    `json:"username"`
	Action     string    `json:"action"`      // e.g., "CREATE", "UPDATE", "DELETE", "START", "STOP"
	EntityType string    `json:"entity_type"` // e.g., "workflow", "source", "sink", "user"
	EntityID   string    `json:"entity_id"`
	Payload    string    `json:"payload,omitempty"` // Details about the change (JSON)
	IP         string    `json:"ip,omitempty"`
}

type CommonFilter struct {
	Page        int
	Limit       int
	Search      string
	VHost       string
	WorkspaceID string
	// WithoutWorkspace limits matches to rows with no workspace — the view you
	// need to find what is left to organise. Mirrors LogFilter.WithoutWorkflow.
	// It takes precedence over WorkspaceID, which is never set at the same time.
	WithoutWorkspace bool
	// Since and Until bound time-based queries (e.g., logs). Zero value means not set.
	Since time.Time `json:"since" omitzero:"true"`
	Until time.Time `json:"until" omitzero:"true"`

	// Workflow filters
	WorkerID string `json:"worker_id,omitempty"`
	OwnerID  string `json:"owner_id,omitempty"`
	Active   *bool  `json:"active,omitempty"`
}

type DashboardSample struct {
	Timestamp       time.Time `json:"timestamp"`
	VHost           string    `json:"vhost"`
	Throughput      float64   `json:"throughput"`
	TotalProcessed  uint64    `json:"total_processed"`
	TotalErrors     uint64    `json:"total_errors"`
	TotalLag        uint64    `json:"total_lag"`
	ErrorRate       float64   `json:"error_rate"`
	AvgLatencyMs    float64   `json:"avg_latency_ms"`
	ActiveWorkflows int       `json:"active_workflows"`
	ActiveWorkers   int       `json:"active_workers"`
}

type DashboardStats struct {
	ActiveSources   int     `json:"active_sources"`
	ActiveSinks     int     `json:"active_sinks"`
	ActiveWorkflows int     `json:"active_workflows"`
	TotalProcessed  uint64  `json:"total_processed"`
	TotalErrors     uint64  `json:"total_errors"`
	TotalLag        uint64  `json:"total_lag"`
	FailedWorkflows int     `json:"failed_workflows"`
	Uptime          int64   `json:"uptime"`
	ActiveWorkers   int     `json:"active_workers"`
	TotalWorkflows  int     `json:"total_workflows"`
	TotalSources    int     `json:"total_sources"`
	TotalSinks      int     `json:"total_sinks"`
	Throughput      float64 `json:"throughput"` // Messages per second

	// Health signals. These answer "is the data moving well?", which the
	// counters above cannot: a pipeline with a rising TotalProcessed and a
	// wedged sink looks identical to a healthy one until someone reads the
	// logs.
	//
	// There is deliberately no DeadLetterCount here. TotalErrors is already
	// exactly that — flushStatsToStorage persists baseErrors +
	// StatusUpdate.DeadLetterCount into total_errors — and showing the same
	// number twice under two names is how a dashboard loses the reader's
	// trust.
	//
	// ErrorRate is derived from the persisted counters and so is cumulative
	// over the workflow's life. The other three are point-in-time readings of
	// engines running on this node, so they reset when an engine restarts and
	// read zero when nothing is running.
	ErrorRate           float64 `json:"error_rate"`     // Dead-lettered share of attempted messages, 0..1
	AvgLatencyMs        float64 `json:"avg_latency_ms"` // Mean end-to-end latency across running engines
	Backpressure        float64 `json:"backpressure"`   // Worst sink buffer fill, 0..1
	CircuitBreakersOpen int     `json:"circuit_breakers_open"`

	// Cluster capacity and utilisation, over exactly the workers ActiveWorkers
	// counts — those that reported a heartbeat inside the last two minutes. A
	// worker that stopped reporting has already been excluded from the count,
	// and counting its cores and disk would describe machines that are no
	// longer there.
	//
	// Totalled rather than averaged, because the question is "how much machine
	// is behind this platform, and how much of it is gone". An average hides a
	// node that is full next to one that is idle, and the full one is the
	// reason anybody opened the page.
	//
	// Workers that report no capacity contribute nothing rather than dragging a
	// total down — see WorkerResources. And one worker per host is assumed:
	// two workers on one machine would count that machine's memory and disk
	// twice. Hermod's topology is a worker per node, and the alternative,
	// deduplicating on a self-reported hostname, is wrong in exactly the
	// container case it would exist to handle.
	CPUCores          int     `json:"cpu_cores"`
	CPUUsage          float64 `json:"cpu_usage"` // 0..1, weighted by each worker's core count
	MemoryTotalBytes  int64   `json:"memory_total_bytes"`
	MemoryUsedBytes   int64   `json:"memory_used_bytes"`
	StorageTotalBytes int64   `json:"storage_total_bytes"`
	StorageUsedBytes  int64   `json:"storage_used_bytes"`
}

type FormSubmission struct {
	ID        string    `json:"id"`
	Timestamp time.Time `json:"timestamp" omitzero:"true"`
	Path      string    `json:"path"`
	Data      []byte    `json:"data"`
	Status    string    `json:"status"` // pending, processing, completed, failed
}

type FormSubmissionFilter struct {
	CommonFilter
	Path   string `json:"path"`
	Status string `json:"status"`
}

type LineageEdge struct {
	SourceID     string `json:"source_id"`
	SourceName   string `json:"source_name"`
	SourceType   string `json:"source_type"`
	SinkID       string `json:"sink_id"`
	SinkName     string `json:"sink_name"`
	SinkType     string `json:"sink_type"`
	WorkflowID   string `json:"workflow_id"`
	WorkflowName string `json:"workflow_name"`
}

type Log struct {
	ID         string    `json:"id"`
	Timestamp  time.Time `json:"timestamp"`
	Level      string    `json:"level"`
	Message    string    `json:"message"`
	Action     string    `json:"action,omitempty"`
	SourceID   string    `json:"source_id,omitempty"`
	SinkID     string    `json:"sink_id,omitempty"`
	WorkflowID string    `json:"workflow_id,omitempty"`
	UserID     string    `json:"user_id,omitempty"`
	Username   string    `json:"username,omitempty"`
	Data       string    `json:"data,omitempty"`
}

type LogFilter struct {
	CommonFilter
	SourceID   string
	SinkID     string
	WorkflowID string
	Level      string
	Action     string
	// WithoutWorkflow limits matches to logs without a workflow_id (NULL).
	WithoutWorkflow bool
}

type MLBlob struct {
	Key       string    `json:"key"`
	Size      int64     `json:"size"`
	UpdatedAt time.Time `json:"updated_at"`
	Data      []byte    `json:"-"`
}

type MLBlobStore interface {
	// PutMLBlob stores data under key, replacing any blob there. A reader
	// sees the old blob or the new one, never a mix.
	PutMLBlob(ctx context.Context, vhost, key string, data []byte) error
	// CreateMLBlob stores data under key only if nothing is there yet, and
	// returns ErrMLBlobExists otherwise: two servers claiming the same key
	// cannot both succeed.
	CreateMLBlob(ctx context.Context, vhost, key string, data []byte) error
	// GetMLBlob returns the blob under key, or ErrNotFound.
	GetMLBlob(ctx context.Context, vhost, key string) ([]byte, error)
	// ListMLBlobs returns the blobs whose key starts with prefix ("" for
	// all), ordered by key, with their data only when withData is set.
	ListMLBlobs(ctx context.Context, vhost, prefix string, withData bool) ([]MLBlob, error)
	// DeleteMLBlobs removes the blobs whose key starts with prefix ("" for
	// every blob of the vhost) and returns how many there were.
	DeleteMLBlobs(ctx context.Context, vhost, prefix string) (int, error)
}

type MLFeedbackEvent struct {
	VHost            string    `json:"vhost"`
	Model            string    `json:"model"`
	RecommendationID string    `json:"recommendation_id"`
	ItemID           string    `json:"id"`
	Outcome          string    `json:"outcome"`
	At               time.Time `json:"at"`
}

type MLFeedbackStore interface {
	// AddMLFeedback stores events, every one or none.
	AddMLFeedback(ctx context.Context, events []MLFeedbackEvent) error
	// CountMLFeedback counts a model's events at or after since, by outcome.
	CountMLFeedback(ctx context.Context, vhost, model string, since time.Time) (map[string]int, error)
	// DeleteMLFeedback removes a model's feedback, or the whole vhost's when
	// model is empty.
	DeleteMLFeedback(ctx context.Context, vhost, model string) error
}

type MLGoLive struct {
	Mode string `json:"mode"`
	// Metric is the metric "if" checks; empty means "score", which is
	// accuracy for a classifier and R² for a regression.
	Metric string   `json:"metric,omitempty"`
	Min    *float64 `json:"min,omitempty"`
	Max    *float64 `json:"max,omitempty"`
}

type MLJob struct {
	ID    string `json:"id"`
	VHost string `json:"vhost"`
	Model string `json:"model"`
	Kind  string `json:"kind"`

	Status string `json:"status"`
	// Progress is how far along the job is, 0 to 1, and ProgressMessage
	// says so in words.
	Progress        float64 `json:"progress"`
	ProgressMessage string  `json:"progress_message,omitempty"`

	// Request is what the job runs, as JSON; its shape depends on Kind.
	// Listings leave it out.
	Request json.RawMessage `json:"request,omitempty"`
	// Result is the answer, as JSON, when it is small enough to keep here.
	// ResultRef is MLJobResultStored when it is kept apart instead.
	// Listings leave both out.
	Result    json.RawMessage `json:"result,omitempty"`
	ResultRef string          `json:"result_ref,omitempty"`
	Error     string          `json:"error,omitempty"`

	// CallbackURL is told when the job ends. CallbackStatus is pending until
	// it has been, delivered or failed after; empty without a URL.
	CallbackURL       string    `json:"callback_url,omitempty"`
	CallbackStatus    string    `json:"callback_status,omitempty"`
	CallbackAttempts  int       `json:"callback_attempts,omitempty"`
	CallbackNextAt    time.Time `json:"-"`
	CallbackLastError string    `json:"callback_error,omitempty"`

	// CallerKind is who submitted it: one of the MLCaller kinds. A job
	// submitted with a serving key (MLCallerREST or MLCallerGRPC) is the
	// only kind that key may read. CreatedBy is the user, when there is one.
	CallerKind string `json:"caller_kind"`
	CreatedBy  string `json:"created_by,omitempty"`

	// CancelRequested asks the Hermod running the job to stop it.
	CancelRequested bool `json:"cancel_requested,omitempty"`
	// Attempts is how many times the job was claimed to run. More than one
	// means a Hermod running it stopped and another took it over.
	Attempts int `json:"attempts"`
	// ClaimedBy holds the job, while it runs or its callback is sent, until
	// ClaimUntil; a claim not renewed by then may be taken over.
	ClaimedBy  string    `json:"-"`
	ClaimUntil time.Time `json:"-"`

	CreatedAt  time.Time  `json:"created_at"`
	StartedAt  *time.Time `json:"started_at,omitempty"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
	// ExpiresAt is when the job and its result are removed.
	ExpiresAt time.Time `json:"expires_at"`
}

type MLJobFilter struct {
	VHost  string
	Model  string
	Status string
	Limit  int
	Offset int
}

type MLJobFinish struct {
	Status    string
	Result    json.RawMessage
	ResultRef string
	Error     string
	At        time.Time
}

type MLJobStore interface {
	// CreateMLJob stores a new job as it is given.
	CreateMLJob(ctx context.Context, j MLJob) error
	// GetMLJob returns one job of the vhost, with its request and result, or
	// ErrNotFound.
	GetMLJob(ctx context.Context, vhost, id string) (MLJob, error)
	// ListMLJobs returns one page of the vhost's jobs, newest first, without
	// their requests and results, and how many match in all.
	ListMLJobs(ctx context.Context, f MLJobFilter) ([]MLJob, int, error)
	// ClaimMLJob takes the oldest job that is queued, or running under a
	// claim that expired before now, for owner until now+ttl, marks it
	// running and counts the attempt. It reports false when there is none.
	ClaimMLJob(ctx context.Context, owner string, ttl time.Duration, now time.Time) (MLJob, bool, error)
	// UpdateMLJobProgress records how far owner's running job is and renews
	// its claim until until. It reports whether cancelling the job was
	// asked for, and ErrMLJobClaimLost when owner no longer holds it.
	UpdateMLJobProgress(ctx context.Context, id, owner string, progress float64, message string, until time.Time) (bool, error)
	// FinishMLJob records how owner's job ended and releases it. A job with
	// a callback URL is then due for its callback. It returns
	// ErrMLJobClaimLost when owner no longer holds it.
	FinishMLJob(ctx context.Context, id, owner string, f MLJobFinish) error
	// CancelMLJob cancels a queued job at once, or asks the Hermod running a
	// running one to stop it, and returns the job. A finished job is
	// returned as it is. It returns ErrNotFound for no such job.
	CancelMLJob(ctx context.Context, vhost, id string, now time.Time) (MLJob, error)
	// ClaimMLJobCallback takes, for owner until now+ttl, a finished job whose
	// callback is pending and due. It reports false when there is none.
	ClaimMLJobCallback(ctx context.Context, owner string, ttl time.Duration, now time.Time) (MLJob, bool, error)
	// RecordMLJobCallback records one delivery attempt of owner's callback
	// and releases the job: status is pending again (with next, when to try
	// next), delivered or failed.
	RecordMLJobCallback(ctx context.Context, id, owner, status string, attempts int, next time.Time, lastError string) error
	// PutMLJobResult keeps a result too large for the job itself.
	PutMLJobResult(ctx context.Context, vhost, id string, result json.RawMessage) error
	// GetMLJobResult reads a result PutMLJobResult kept, or ErrNotFound.
	GetMLJobResult(ctx context.Context, vhost, id string) (json.RawMessage, error)
	// DeleteExpiredMLJobs removes every job, and its result, that expired
	// before now, and returns how many jobs went.
	DeleteExpiredMLJobs(ctx context.Context, now time.Time) (int, error)
	// DeleteMLJobs removes every job, and result, the vhost holds.
	DeleteMLJobs(ctx context.Context, vhost string) error
}

type MLModel struct {
	VHost       string `json:"vhost"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`

	// Backend, URL, RemoteModel and RemoteVersion are inference.Target's
	// Backend, URL, Model and Version.
	Backend       inference.Backend `json:"backend"`
	URL           string            `json:"url"`
	RemoteModel   string            `json:"remote_model,omitempty"`
	RemoteVersion string            `json:"remote_version,omitempty"`

	// TokenSecret names a secret of the same vhost whose value is sent as a
	// bearer token. The token itself is never stored on the model.
	TokenSecret string `json:"token_secret,omitempty"`

	InputName string   `json:"input_name,omitempty"`
	Features  []string `json:"features,omitempty"`
	// FeatureTypes is feature -> number, string or bool, where it is known:
	// for a model Hermod trained, from the dataset it was trained on.
	FeatureTypes map[string]string `json:"feature_types,omitempty"`
	TimeoutMs    int               `json:"timeout_ms,omitempty"`

	// MCPExposed offers the model as a predict_<name> tool on Hermod's MCP
	// server to callers who may use its vhost. Off unless someone turns it on.
	MCPExposed bool `json:"mcp_exposed"`

	// ServingKeyHash is the SHA-256 of the key an application presents to call
	// the model through the serving endpoints. Empty means serving is off. The
	// key itself is shown once, when it is made, and never stored.
	ServingKeyHash string `json:"-"`
	// Serving reports whether a serving key is set; it is what the API shows.
	Serving bool `json:"serving"`

	// Monitoring is how the model's predictions are logged and its drift
	// judged. The zero value logs nothing and uses the default thresholds.
	Monitoring MLMonitoring `json:"monitoring"`
	// Retrain is when a trained model trains again by itself, nil for never.
	// RetrainStatus is what its last training did. PutMLModel changes
	// neither; MLRetrainStore does.
	Retrain       *MLRetrainPolicy `json:"retrain,omitempty"`
	RetrainStatus *MLRetrainStatus `json:"retrain_status,omitempty"`

	// Scoring is where a trained model's predictions are computed:
	// MLScoringWorker (also the meaning of empty) or MLScoringInProcess.
	// PutMLModel does not change it; MLScoringStore does.
	Scoring string `json:"scoring,omitempty"`

	// Task is what a model Hermod trained does, as its live version (or,
	// before one is live, its latest) says: classification, regression or
	// MLTaskRecommendation. A recommender is called with a person or an
	// item, not rows. Empty for a model served elsewhere, and for one
	// trained before the task was kept.
	Task string `json:"task,omitempty"`

	UpdatedBy string    `json:"updated_by,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type MLModelStore interface {
	// ListMLModels returns the vhost's models ordered by name.
	ListMLModels(ctx context.Context, vhost string) ([]MLModel, error)
	// GetMLModel returns one model, or ErrNotFound.
	GetMLModel(ctx context.Context, vhost, name string) (MLModel, error)
	// PutMLModel creates the model or replaces its definition. It never
	// changes the serving key; SetMLModelServingKey does.
	PutMLModel(ctx context.Context, m MLModel) error
	// SetMLModelServingKey stores the hash of a new serving key, or turns
	// serving off when hash is empty. It returns ErrNotFound for no such model.
	SetMLModelServingKey(ctx context.Context, vhost, name, hash string) error
	// DeleteMLModel removes one model, or returns ErrNotFound.
	DeleteMLModel(ctx context.Context, vhost, name string) error
	// DeleteMLModels removes every model the vhost holds.
	DeleteMLModels(ctx context.Context, vhost string) error
}

type MLMonitoring struct {
	// LogSampleRate is the share of predictions logged, 0 to 1.
	LogSampleRate float64 `json:"log_sample_rate,omitempty"`
	// LogMaskFields are input or output fields masked in a logged row, as
	// dotted paths; "*" masks every string.
	LogMaskFields []string `json:"log_mask_fields,omitempty"`
	// LogMaskType is one of MLMaskTypes; empty means "all".
	LogMaskType string `json:"log_mask_type,omitempty"`
	// LogRetention is how long a logged row is kept, as "7d" or "12h"; empty
	// means DefaultMLLogRetention.
	LogRetention string `json:"log_retention,omitempty"`

	// DriftWarn and DriftAlert are the population stability index at which a
	// feature is reported as drifting, and at which an alert is sent; zero
	// means the default.
	DriftWarn  float64 `json:"drift_warn,omitempty"`
	DriftAlert float64 `json:"drift_alert,omitempty"`
}

type MLPredictionLog struct {
	VHost     string         `json:"vhost"`
	Model     string         `json:"model"`
	Version   string         `json:"version,omitempty"`
	Timestamp time.Time      `json:"timestamp"`
	Inputs    map[string]any `json:"inputs"`
	Outputs   map[string]any `json:"outputs"`
	// LatencyMs is how long the whole call, of which this row was part, took.
	LatencyMs  float64 `json:"latency_ms"`
	CallerKind string  `json:"caller_kind"`
	CallerID   string  `json:"caller_id,omitempty"`
}

type MLPredictionLogStore interface {
	// InsertMLPredictionLogs writes a batch of logged predictions.
	InsertMLPredictionLogs(ctx context.Context, logs []MLPredictionLog) error
	// ListMLPredictionLogs returns a model's most recent logged predictions,
	// newest first, at most limit (bounded by MaxMLPredictionLogPage).
	ListMLPredictionLogs(ctx context.Context, vhost, model string, limit int) ([]MLPredictionLog, error)
	// PurgeMLPredictionLogs removes logged predictions older than before: of
	// one model, of every model of the vhost when model is empty, or of
	// everything when vhost is empty too.
	PurgeMLPredictionLogs(ctx context.Context, vhost, model string, before time.Time) error
	// DeleteMLPredictionLogs removes every logged prediction of a model, or of
	// every model of the vhost when model is empty.
	DeleteMLPredictionLogs(ctx context.Context, vhost, model string) error
}

type MLQuotaStore interface {
	// GetMLQuotas returns the vhost's quotas, or ErrNotFound when none are set.
	GetMLQuotas(ctx context.Context, vhost string) (MLQuotas, error)
	// PutMLQuotas replaces the vhost's quotas.
	PutMLQuotas(ctx context.Context, q MLQuotas) error
	// DeleteMLQuotas removes the vhost's quotas; none is not an error.
	DeleteMLQuotas(ctx context.Context, vhost string) error
}

type MLQuotas struct {
	VHost string `json:"vhost"`

	// MaxDatasets bounds how many datasets the vhost holds.
	MaxDatasets *int64 `json:"max_datasets"`
	// MaxDatasetRows bounds the rows one dataset holds.
	MaxDatasetRows *int64 `json:"max_dataset_rows"`
	// MaxDatasetBytes bounds what one fill of a dataset sends to the ML
	// worker: the file as uploaded, or the rows of a query as JSON.
	MaxDatasetBytes *int64 `json:"max_dataset_bytes"`
	// MaxModels bounds how many models the vhost registers or trains.
	MaxModels *int64 `json:"max_models"`
	// MaxConcurrentTrainings bounds the vhost's trainings running at once.
	MaxConcurrentTrainings *int64 `json:"max_concurrent_trainings"`
	// MaxPredictionsPerSecond bounds the rows the vhost's models are sent per
	// second.
	MaxPredictionsPerSecond *float64 `json:"max_predictions_per_second"`

	UpdatedBy string    `json:"updated_by,omitempty"`
	UpdatedAt time.Time `json:"updated_at"`
}

type MLRetrainPolicy struct {
	// Schedule is a five-field cron expression, or a descriptor such as
	// "@daily". Empty means no schedule.
	Schedule string `json:"schedule,omitempty"`
	// NewRows trains again once the dataset holds this many rows more than
	// when the model last trained. Zero means no row trigger.
	NewRows int `json:"new_rows,omitempty"`

	Spec   worker.TrainSpec `json:"spec"`
	GoLive MLGoLive         `json:"go_live"`

	UpdatedBy string    `json:"updated_by,omitempty"`
	UpdatedAt time.Time `json:"updated_at"`
}

type MLRetrainStatus struct {
	// At is when the last retraining ran; zero until one has. Trigger is
	// "schedule" or "new_rows".
	At      time.Time `json:"at"`
	Trigger string    `json:"trigger,omitempty"`
	// Version is the version it made, Live whether that version went live and
	// Reason why, in words. Error is set instead when it failed.
	Version string `json:"version,omitempty"`
	Live    bool   `json:"live"`
	Reason  string `json:"reason,omitempty"`
	Error   string `json:"error,omitempty"`

	// DatasetRows is how many rows the dataset held when the model last
	// trained, by any trigger, and TrainedAt when that was.
	DatasetRows int       `json:"dataset_rows"`
	TrainedAt   time.Time `json:"trained_at"`
}

type MLRetrainStore interface {
	// ListRetrainingMLModels returns every model, of every vhost, that has a
	// retrain policy.
	ListRetrainingMLModels(ctx context.Context) ([]MLModel, error)
	// SetMLModelRetrain stores the model's retrain policy, or clears it when
	// p is nil. It returns ErrNotFound for no such model.
	SetMLModelRetrain(ctx context.Context, vhost, name string, p *MLRetrainPolicy) error
	// SetMLModelRetrainStatus stores what the model's last training did. It
	// returns ErrNotFound for no such model.
	SetMLModelRetrainStatus(ctx context.Context, vhost, name string, st MLRetrainStatus) error
	// ClaimMLModelTraining marks the model as being trained by owner for ttl,
	// and reports whether it could: false while another owner's claim has not
	// expired. The owner may claim again to extend its own. It returns
	// ErrNotFound for no such model.
	ClaimMLModelTraining(ctx context.Context, vhost, name, owner string, ttl time.Duration) (bool, error)
	// ReleaseMLModelTraining ends owner's claim; anyone else's is left alone.
	ReleaseMLModelTraining(ctx context.Context, vhost, name, owner string) error
}

type MLSchedule struct {
	VHost    string          `json:"vhost"`
	Kind     string          `json:"kind"`
	Name     string          `json:"name"`
	Schedule string          `json:"schedule"`
	Spec     json.RawMessage `json:"spec"`

	LastRun   time.Time `json:"last_run"`
	LastRows  int       `json:"last_rows"`
	LastError string    `json:"last_error,omitempty"`

	UpdatedBy string    `json:"updated_by,omitempty"`
	UpdatedAt time.Time `json:"updated_at"`
}

type MLScheduleStore interface {
	// ListMLSchedules returns every schedule of every vhost.
	ListMLSchedules(ctx context.Context) ([]MLSchedule, error)
	// GetMLSchedule returns one schedule, or ErrNotFound.
	GetMLSchedule(ctx context.Context, vhost, kind, name string) (MLSchedule, error)
	// PutMLSchedule saves a schedule's definition, keeping what its last run
	// did. UpdatedAt is set here.
	PutMLSchedule(ctx context.Context, s MLSchedule) error
	// DeleteMLSchedule removes a schedule, or returns ErrNotFound.
	DeleteMLSchedule(ctx context.Context, vhost, kind, name string) error
	// SetMLScheduleRun records what a run did. A schedule removed meanwhile
	// is not an error.
	SetMLScheduleRun(ctx context.Context, vhost, kind, name string, at time.Time, rows int, runErr string) error
	// ClaimMLSchedule marks the schedule as run by owner for ttl, and
	// reports whether it could: false while another owner's claim has not
	// expired, or for no such schedule. The owner may claim again.
	ClaimMLSchedule(ctx context.Context, vhost, kind, name, owner string, ttl time.Duration) (bool, error)
	// ReleaseMLSchedule ends owner's claim; anyone else's is left alone.
	ReleaseMLSchedule(ctx context.Context, vhost, kind, name, owner string) error
	// DeleteMLSchedules removes every schedule of a vhost.
	DeleteMLSchedules(ctx context.Context, vhost string) error
}

type MLScoringStore interface {
	// SetMLModelScoring stores where the model is scored. It returns
	// ErrNotFound for no such model.
	SetMLModelScoring(ctx context.Context, vhost, name, scoring string) error
}

type MLScript struct {
	VHost   string `json:"vhost"`
	Name    string `json:"name"`
	Version int    `json:"version"`
	SHA256  string `json:"sha256"`
	// Source is empty in listings; GetMLScript fills it.
	Source      string    `json:"source,omitempty"`
	Description string    `json:"description,omitempty"`
	CreatedBy   string    `json:"created_by,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
}

type MLScriptStore interface {
	// ListMLScripts returns the latest version of each of the vhost's
	// scripts, ordered by name, without their source.
	ListMLScripts(ctx context.Context, vhost string) ([]MLScript, error)
	// ListMLScriptVersions returns every version of one script, newest
	// first, without their source.
	ListMLScriptVersions(ctx context.Context, vhost, name string) ([]MLScript, error)
	// GetMLScript returns the latest version of a script with its source, or
	// ErrNotFound.
	GetMLScript(ctx context.Context, vhost, name string) (MLScript, error)
	// PutMLScript saves s.Source as the script's next version, unless it is
	// the source of the latest version already, and returns the version that
	// holds it. Version, SHA256 and CreatedAt are set here.
	PutMLScript(ctx context.Context, s MLScript) (MLScript, error)
	// DeleteMLScript removes every version of a script, or returns ErrNotFound.
	DeleteMLScript(ctx context.Context, vhost, name string) error
	// DeleteMLScripts removes every script the vhost holds.
	DeleteMLScripts(ctx context.Context, vhost string) error
}

type MessageTrace struct {
	ID         string             `json:"id"`
	MessageID  string             `json:"message_id"`
	WorkflowID string             `json:"workflow_id"`
	Steps      []hermod.TraceStep `json:"steps"`
	CreatedAt  time.Time          `json:"created_at"`

	// Summary fields, carried on the parent row so the trace list never has to
	// touch the step table. Listing used to aggregate every step a workflow had
	// ever produced — measured on PostgreSQL 17, a sequential scan of 250k rows
	// and ~390 MB of I/O to return 25 of them — because "when did this message
	// start" was only derivable as MIN(timestamp) over its steps. It is now
	// written once, when the steps are.
	StepCount  int   `json:"step_count"`
	ErrorCount int   `json:"error_count"`
	DurationMs int64 `json:"duration_ms"`
}

type MissingRef struct {
	Kind   string `json:"kind"` // "source" or "sink"
	ID     string `json:"id"`
	NodeID string `json:"node_id,omitempty"`
}

type OutboxItem = hermod.OutboxItem

type Plugin struct {
	ID          string     `json:"id"`
	Name        string     `json:"name"`
	Description string     `json:"description"`
	Author      string     `json:"author"`
	Stars       int        `json:"stars"`
	Category    string     `json:"category"`
	Certified   bool       `json:"certified"`
	Type        string     `json:"type"` // WASM, Connector, Transformer
	WasmURL     string     `json:"wasm_url,omitempty"`
	Installed   bool       `json:"installed"`
	InstalledAt *time.Time `json:"installed_at" omitzero:"true"`
	// CreatedAt is the sort key the plugin list pages on. Storage stamps it when a
	// caller leaves it zero and never rewrites it on update. See Workflow.CreatedAt.
	CreatedAt time.Time `json:"created_at" bson:"created_at"`
}

type Role string

type Schema struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	Version   int       `json:"version"`
	Type      string    `json:"type"`
	Content   string    `json:"content"`
	CreatedAt time.Time `json:"created_at" omitzero:"true"`
}

type Sink struct {
	ID          string           `json:"id"`
	Name        string           `json:"name"`
	Type        string           `json:"type"`
	VHost       string           `json:"vhost"`
	Active      bool             `json:"active"`
	Status      string           `json:"status,omitempty"`
	WorkerID    string           `json:"worker_id"`
	WorkspaceID string           `json:"workspace_id,omitempty"`
	Config      hermod.StringMap `json:"config"`
	// CreatedAt is the sort key the sink list pages on. Storage stamps it
	// when a caller leaves it zero and never rewrites it on update, so it stays
	// the creation time rather than the last-touched time. See Workflow.CreatedAt.
	CreatedAt time.Time `json:"created_at" bson:"created_at"`
}

type Source struct {
	ID          string            `json:"id"`
	Name        string            `json:"name"`
	Type        string            `json:"type"`
	VHost       string            `json:"vhost"`
	Active      bool              `json:"active"`
	Status      string            `json:"status,omitempty"`
	WorkerID    string            `json:"worker_id"`
	WorkspaceID string            `json:"workspace_id,omitempty"`
	Config      hermod.StringMap  `json:"config"`
	Sample      string            `json:"sample,omitempty"`
	State       map[string]string `json:"state" omitzero:"true"`
	// CreatedAt is the sort key the source list pages on. Storage stamps it
	// when a caller leaves it zero and never rewrites it on update, so it stays
	// the creation time rather than the last-touched time. See Workflow.CreatedAt.
	CreatedAt time.Time `json:"created_at" bson:"created_at"`
}

type Storage interface {
	// Init performs storage initialization/migrations and is safe to call multiple times.
	Init(ctx context.Context) error

	// Ping checks the connection to the storage.
	Ping(ctx context.Context) error

	ListSources(ctx context.Context, filter CommonFilter) ([]Source, int, error)
	CreateSource(ctx context.Context, src Source) error
	UpdateSource(ctx context.Context, src Source) error
	UpdateSourceStatus(ctx context.Context, id string, status string) error
	UpdateSourceState(ctx context.Context, id string, state map[string]string) error
	// UpdateSourceSample writes only the stored preview payload. Storing a
	// sample through UpdateSource carried every other column along with it,
	// from whatever copy of the source the caller happened to hold.
	UpdateSourceSample(ctx context.Context, id string, sample string) error
	DeleteSource(ctx context.Context, id string) error
	GetSource(ctx context.Context, id string) (Source, error)

	ListSinks(ctx context.Context, filter CommonFilter) ([]Sink, int, error)
	CreateSink(ctx context.Context, snk Sink) error
	UpdateSink(ctx context.Context, snk Sink) error

	// ReEncryptSecrets rewrites every stored credential under newKey. Key
	// rotation must call this *before* installing the new key: rotating
	// without it leaves every password and API key encrypted under a key the
	// process no longer has.
	ReEncryptSecrets(ctx context.Context, newKey string) error
	UpdateSinkStatus(ctx context.Context, id string, status string) error
	DeleteSink(ctx context.Context, id string) error
	GetSink(ctx context.Context, id string) (Sink, error)

	ListUsers(ctx context.Context, filter CommonFilter) ([]User, int, error)
	CreateUser(ctx context.Context, user User) error
	UpdateUser(ctx context.Context, user User) error
	DeleteUser(ctx context.Context, id string) error
	GetUser(ctx context.Context, id string) (User, error)
	GetUserByUsername(ctx context.Context, username string) (User, error)
	GetUserByEmail(ctx context.Context, email string) (User, error)

	ListVHosts(ctx context.Context, filter CommonFilter) ([]VHost, int, error)
	CreateVHost(ctx context.Context, vhost VHost) error
	UpdateVHost(ctx context.Context, vhost VHost) error
	DeleteVHost(ctx context.Context, id string) error
	GetVHost(ctx context.Context, id string) (VHost, error)

	ListWorkflows(ctx context.Context, filter CommonFilter) ([]Workflow, int, error)
	ListWorkspaces(ctx context.Context) ([]Workspace, error)
	CreateWorkspace(ctx context.Context, ws Workspace) error
	UpdateWorkspace(ctx context.Context, ws Workspace) error
	GetWorkspace(ctx context.Context, id string) (Workspace, error)
	DeleteWorkspace(ctx context.Context, id string) error
	// ClearWorkspaceAssignments removes every workflow, source and sink from
	// the given workspace and reports how many rows it touched. Deleting a
	// workspace without this leaves members pointing at an id that no longer
	// resolves: the list renders a raw UUID, no filter matches them, and the
	// quota checks stop applying because GetWorkspace errors and they bail.
	ClearWorkspaceAssignments(ctx context.Context, workspaceID string) (int, error)
	CreateWorkflow(ctx context.Context, wf Workflow) error
	UpdateWorkflow(ctx context.Context, wf Workflow) error
	UpdateWorkflowStatus(ctx context.Context, id string, status string) error
	UpdateWorkflowStats(ctx context.Context, id string, processed, errors, lag uint64) error
	DeleteWorkflow(ctx context.Context, id string) error
	GetWorkflow(ctx context.Context, id string) (Workflow, error)

	// Lease-based ownership for workflows
	// AcquireWorkflowLease attempts to set owner_id and extend lease_until atomically with TTL seconds.
	// Returns true if the lease was acquired.
	AcquireWorkflowLease(ctx context.Context, workflowID, ownerID string, ttlSeconds int) (bool, error)
	// RenewWorkflowLease extends lease_until for an existing owner if not expired yet. Returns true if renewed.
	RenewWorkflowLease(ctx context.Context, workflowID, ownerID string, ttlSeconds int) (bool, error)
	// ReleaseWorkflowLease clears ownership if owned by ownerID.
	ReleaseWorkflowLease(ctx context.Context, workflowID, ownerID string) error

	ListWorkers(ctx context.Context, filter CommonFilter) ([]Worker, int, error)
	CreateWorker(ctx context.Context, worker Worker) error
	UpdateWorker(ctx context.Context, worker Worker) error
	UpdateWorkerHeartbeat(ctx context.Context, id string, res WorkerResources) error
	DeleteWorker(ctx context.Context, id string) error
	GetWorker(ctx context.Context, id string) (Worker, error)

	ListLogs(ctx context.Context, filter LogFilter) ([]Log, int, error)
	CreateLog(ctx context.Context, log Log) error
	CreateLogs(ctx context.Context, logs []Log) error
	DeleteLogs(ctx context.Context, filter LogFilter) error
	PurgeLogs(ctx context.Context, before time.Time) error

	ListAuditLogs(ctx context.Context, filter AuditFilter) ([]AuditLog, int, error)
	CreateAuditLog(ctx context.Context, log AuditLog) error
	PurgeAuditLogs(ctx context.Context, before time.Time) error
	PurgeMessageTraces(ctx context.Context, retention TraceRetention) error
	DeleteWorkflowMessageTraces(ctx context.Context, workflowID string) error

	ListWebhookRequests(ctx context.Context, filter WebhookRequestFilter) ([]WebhookRequest, int, error)
	CreateWebhookRequest(ctx context.Context, req WebhookRequest) error
	GetWebhookRequest(ctx context.Context, id string) (WebhookRequest, error)
	DeleteWebhookRequests(ctx context.Context, filter WebhookRequestFilter) error

	CreateFormSubmission(ctx context.Context, sub FormSubmission) error
	ListFormSubmissions(ctx context.Context, filter FormSubmissionFilter) ([]FormSubmission, int, error)
	GetFormSubmission(ctx context.Context, id string) (FormSubmission, error)
	UpdateFormSubmissionStatus(ctx context.Context, id string, status string) error
	DeleteFormSubmissions(ctx context.Context, filter FormSubmissionFilter) error

	GetSetting(ctx context.Context, key string) (string, error)
	SaveSetting(ctx context.Context, key string, value string) error

	// Node State Management
	UpdateNodeState(ctx context.Context, workflowID, nodeID string, state any) error
	GetNodeStates(ctx context.Context, workflowID string) (map[string]any, error)

	// Schema Registry
	ListSchemas(ctx context.Context, name string) ([]Schema, error)
	ListAllSchemas(ctx context.Context) ([]Schema, error)
	GetSchema(ctx context.Context, name string, version int) (Schema, error)
	GetLatestSchema(ctx context.Context, name string) (Schema, error)
	CreateSchema(ctx context.Context, schema Schema) error

	// Message Tracing
	RecordTraceStep(ctx context.Context, workflowID, messageID string, step hermod.TraceStep) error
	GetMessageTrace(ctx context.Context, workflowID, messageID string) (MessageTrace, error)
	ListMessageTraces(ctx context.Context, workflowID string, filter TraceFilter) ([]MessageTrace, error)

	// Workflow Versioning
	CreateWorkflowVersion(ctx context.Context, version WorkflowVersion) error
	ListWorkflowVersions(ctx context.Context, workflowID string) ([]WorkflowVersion, error)
	GetWorkflowVersion(ctx context.Context, workflowID string, version int) (WorkflowVersion, error)

	// Transactional Outbox
	CreateOutboxItem(ctx context.Context, item OutboxItem) error
	ListOutboxItems(ctx context.Context, status string, limit int) ([]OutboxItem, error)
	DeleteOutboxItem(ctx context.Context, id string) error
	UpdateOutboxItem(ctx context.Context, item OutboxItem) error

	// Lineage
	GetLineage(ctx context.Context) ([]LineageEdge, error)

	// Marketplace
	ListPlugins(ctx context.Context) ([]Plugin, error)
	GetPlugin(ctx context.Context, id string) (Plugin, error)
	InstallPlugin(ctx context.Context, id string) error
	UninstallPlugin(ctx context.Context, id string) error

	// Approvals
	ListApprovals(ctx context.Context, filter ApprovalFilter) ([]Approval, int, error)
	CreateApproval(ctx context.Context, app Approval) error
	GetApproval(ctx context.Context, id string) (Approval, error)
	UpdateApprovalStatus(ctx context.Context, id string, status string, processedBy string, notes string, formData map[string]any) error
	DeleteApproval(ctx context.Context, id string) error

	// Suspended Messages
	CreateSuspendedMessage(ctx context.Context, m SuspendedMessage) error
	ListSuspendedMessages(ctx context.Context, workflowID string, before time.Time) ([]SuspendedMessage, error)
	DeleteSuspendedMessage(ctx context.Context, id string) error

	// Aggregated Dashboard Stats
	GetDashboardStats(ctx context.Context, vhost string) (DashboardStats, error)

	// Dashboard history. Samples are appended on an interval so the dashboard
	// chart survives a page reload; PurgeDashboardHistory bounds the table.
	RecordDashboardSample(ctx context.Context, sample DashboardSample) error
	GetDashboardHistory(ctx context.Context, vhost string, since time.Time, limit int) ([]DashboardSample, error)
	PurgeDashboardHistory(ctx context.Context, before time.Time) error
}

type StoredStep struct {
	NodeID    string        `bson:"node_id" json:"node_id"`
	Timestamp time.Time     `bson:"timestamp" json:"timestamp"`
	Duration  time.Duration `bson:"duration,omitempty" json:"duration,omitempty"`
	AfterKey  string        `bson:"after_key,omitempty" json:"after_key,omitempty"`
	Error     string        `bson:"error,omitempty" json:"error,omitempty"`
	Lineage   string        `bson:"lineage,omitempty" json:"lineage,omitempty"`

	// Documents written before payload dedup carry the maps inline, under the
	// field names the driver derived from hermod.TraceStep's own fields. They
	// are read and never written, so an upgrade needs no backfill.
	LegacyBefore map[string]any `bson:"before,omitempty" json:"before,omitempty"`
	LegacyAfter  map[string]any `bson:"after,omitempty" json:"after,omitempty"`
}

type StoredTrace struct {
	ID         string    `bson:"id" json:"id"`
	WorkflowID string    `bson:"workflow_id" json:"workflow_id"`
	MessageID  string    `bson:"message_id" json:"message_id"`
	CreatedAt  time.Time `bson:"created_at" json:"created_at"`

	Steps []StoredStep `bson:"steps" json:"steps"`

	// Payloads maps a content key to the encoded payload that produced it.
	// Compressed, and self-describing about how — see EncodeTracePayload.
	Payloads map[string][]byte `bson:"payloads,omitempty" json:"payloads,omitempty"`
}

type SuspendedMessage struct {
	ID         string            `json:"id"`
	WorkflowID string            `json:"workflow_id"`
	NodeID     string            `json:"node_id"`
	Payload    []byte            `json:"payload"`
	Metadata   map[string]string `json:"metadata"`
	Data       map[string]any    `json:"data"`
	ResumeAt   time.Time         `json:"resume_at"`
	CreatedAt  time.Time         `json:"created_at"`
}

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

type TraceFilter struct {
	Before time.Time
	Limit  int
	Offset int
}

type TraceRetention struct {
	// Keep maps a workflow id to the oldest trace step it keeps.
	//
	// A workflow with no entry here keeps everything it has. Either no window
	// is configured or the configured one could not be parsed, and neither is
	// a licence to delete: an operator-supplied window has no safe default,
	// because a short one deletes traces nobody asked to lose and none at all
	// restores the growth bug this mechanism exists to prevent.
	Keep map[string]time.Time

	// Live is every workflow that exists, including those absent from Keep.
	//
	// Traces of a workflow that is not here are unreachable — the viewer
	// reaches a trace through its workflow, and ListMessageTraces takes a
	// workflow id — so they are swept regardless of age. Nothing else removes
	// them: DeleteWorkflow deletes one row.
	Live map[string]struct{}

	// LiveIsComplete reports whether Live really is every workflow there is.
	//
	// Not inferred from Live being non-empty, and not a detail. The caller
	// reads workflows through a paged list; on a deployment with more
	// workflows than it asked for, every workflow past the first page would
	// look like a deleted one and have its traces swept. When this is false
	// the orphan sweep is skipped and everything else still runs.
	LiveIsComplete bool
}

type TraceStep = hermod.TraceStep

type Transformation struct {
	Type   string         `json:"type"`
	Config map[string]any `json:"config"`
}

type UnitTest struct {
	Name           string         `json:"name"`
	Input          map[string]any `json:"input"`
	ExpectedOutput map[string]any `json:"expected_output"`
	Description    string         `json:"description,omitempty"`
}

type User struct {
	ID               string   `json:"id"`
	Username         string   `json:"username"`
	Password         string   `json:"password,omitempty"`
	FullName         string   `json:"full_name"`
	Email            string   `json:"email"`
	Role             Role     `json:"role"`
	VHosts           []string `json:"vhosts"`
	TwoFactorEnabled bool     `json:"two_factor_enabled"`
	TwoFactorSecret  string   `json:"two_factor_secret,omitempty"`
	// CreatedAt is the sort key the user list pages on. Storage stamps it when a
	// caller leaves it zero and never rewrites it on update. See Workflow.CreatedAt.
	CreatedAt time.Time `json:"created_at" bson:"created_at"`
}

type VHost struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	// CreatedAt is the sort key the vhost list pages on. Storage stamps it when a
	// caller leaves it zero and never rewrites it on update. See Workflow.CreatedAt.
	CreatedAt time.Time `json:"created_at" bson:"created_at"`
}

type VHostSecret struct {
	VHost     string    `json:"vhost"`
	Name      string    `json:"name"`
	Value     string    `json:"-"`
	UpdatedBy string    `json:"updated_by"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type VHostSecretStore interface {
	// ListVHostSecrets returns the vhost's secrets ordered by name, without
	// their values.
	ListVHostSecrets(ctx context.Context, vhost string) ([]VHostSecret, error)
	// GetVHostSecret returns one secret with its value, or ErrNotFound.
	GetVHostSecret(ctx context.Context, vhost, name string) (VHostSecret, error)
	// PutVHostSecret creates the secret, or replaces its value if the vhost
	// already holds the name.
	PutVHostSecret(ctx context.Context, secret VHostSecret) error
	// DeleteVHostSecret removes one secret, or returns ErrNotFound.
	DeleteVHostSecret(ctx context.Context, vhost, name string) error
	// DeleteVHostSecrets removes every secret the vhost holds.
	DeleteVHostSecrets(ctx context.Context, vhost string) error
}

type WebhookRequest struct {
	ID        string            `json:"id"`
	Timestamp time.Time         `json:"timestamp" omitzero:"true"`
	Path      string            `json:"path"`
	Method    string            `json:"method"`
	Headers   map[string]string `json:"headers"`
	Body      []byte            `json:"body"`
}

type WebhookRequestFilter struct {
	CommonFilter
	Path string `json:"path"`
}

type Worker struct {
	ID          string     `json:"id"`
	Name        string     `json:"name" bson:"name"`
	Host        string     `json:"host" bson:"host"`
	Port        int        `json:"port" bson:"port"`
	Description string     `json:"description" bson:"description"`
	Token       string     `json:"token" bson:"token"`
	LastSeen    *time.Time `json:"last_seen" omitzero:"true" bson:"last_seen"`

	// Resources are inlined rather than nested so the JSON and BSON shapes are
	// unchanged for the two fields that were already here.
	//
	// The bson tags on the fields above are load-bearing and were missing. The
	// driver's default is the lowercased Go name, so this struct decoded
	// "lastseen", "cpuusage" and "memoryusage" while UpdateWorkerHeartbeat wrote
	// "last_seen", "cpu_usage" and "memory_usage" — meaning that on the MongoDB
	// backend every worker read back with a nil LastSeen and no usage at all,
	// which the UI renders as permanently Offline.
	WorkerResources `bson:",inline"`

	// Draining is a transient flag (never persisted) used to signal a running
	// worker that the platform has requested a graceful shutdown. It is set on
	// API responses by the platform when an administrator triggers a shutdown.
	Draining bool `json:"draining,omitempty" bson:"-"`
	// CreatedAt is the sort key the worker list pages on. Storage stamps it when a
	// caller leaves it zero and never rewrites it on update. See Workflow.CreatedAt.
	CreatedAt time.Time `json:"created_at" bson:"created_at"`
}

type WorkerResources struct {
	// CPUUsage and MemoryUsage are fractions in 0..1, not percentages. They
	// predate the rest of this struct and keep their column and JSON names.
	CPUUsage    float64 `json:"cpu_usage,omitempty" bson:"cpu_usage,omitempty"`
	MemoryUsage float64 `json:"memory_usage,omitempty" bson:"memory_usage,omitempty"`

	// CPUCores is the number of logical CPUs visible to the worker process.
	CPUCores int `json:"cpu_cores,omitempty" bson:"cpu_cores,omitempty"`

	// MemoryTotalBytes and MemoryUsedBytes describe physical memory.
	MemoryTotalBytes int64 `json:"memory_total_bytes,omitempty" bson:"memory_total_bytes,omitempty"`
	MemoryUsedBytes  int64 `json:"memory_used_bytes,omitempty" bson:"memory_used_bytes,omitempty"`

	// StorageTotalBytes and StorageUsedBytes describe the filesystem holding
	// the worker's data directory — where SQLite metadata, WAL files and trace
	// payloads are written — rather than every disk on the box. That is the one
	// a full disk stops Hermod on, and the one an operator can act on.
	StorageTotalBytes int64 `json:"storage_total_bytes,omitempty" bson:"storage_total_bytes,omitempty"`
	StorageUsedBytes  int64 `json:"storage_used_bytes,omitempty" bson:"storage_used_bytes,omitempty"`
}

type Workflow struct {
	ID                string         `json:"id"`
	Name              string         `json:"name"`
	VHost             string         `json:"vhost"`
	Active            bool           `json:"active"`
	Status            string         `json:"status,omitempty"`
	WorkerID          string         `json:"worker_id"`
	OwnerID           string         `json:"owner_id,omitempty"`
	LeaseUntil        *time.Time     `json:"lease_until" omitzero:"true"`
	Nodes             []WorkflowNode `json:"nodes"`
	Edges             []WorkflowEdge `json:"edges"`
	DeadLetterSinkID  string         `json:"dead_letter_sink_id,omitempty"`
	PrioritizeDLQ     bool           `json:"prioritize_dlq,omitempty"`
	MaxRetries        int            `json:"max_retries,omitempty"`
	RetryInterval     string         `json:"retry_interval,omitempty"`
	ReconnectInterval string         `json:"reconnect_interval,omitempty"`
	DryRun            bool           `json:"dry_run,omitempty"`
	IdleTimeout       string         `json:"idle_timeout,omitempty"` // e.g. "5m"
	Tier              WorkflowTier   `json:"tier,omitempty"`
	// RetentionDays optionally overrides global log retention for this workflow.
	// nil means inherit the global setting; 0 means keep forever; >0 means days to retain.
	RetentionDays     *int     `json:"retention_days,omitempty"`
	SchemaType        string   `json:"schema_type,omitempty"`
	Schema            string   `json:"schema,omitempty"`
	Cron              string   `json:"cron,omitempty"`
	DLQThreshold      int      `json:"dlq_threshold,omitempty"`
	TraceSampleRate   float64  `json:"trace_sample_rate,omitempty"`
	Tags              []string `json:"tags" omitzero:"true"`
	TraceRetention    string   `json:"trace_retention,omitempty"` // e.g. "7d", "30d"
	AuditRetention    string   `json:"audit_retention,omitempty"` // e.g. "30d", "365d"
	WorkspaceID       string   `json:"workspace_id,omitempty"`
	CPURequest        float64  `json:"cpu_request,omitempty"`
	MemoryRequest     float64  `json:"memory_request,omitempty"`
	ThroughputRequest int      `json:"throughput_request,omitempty"`
	TotalProcessed    uint64   `json:"total_processed,omitempty"`
	TotalErrors       uint64   `json:"total_errors,omitempty"`
	TotalLag          uint64   `json:"total_lag,omitempty"`
	// CreatedAt is the sort key the workflow list pages on. Storage stamps it
	// when a caller leaves it zero and never rewrites it on update, so it stays
	// the creation time rather than the last-touched time. The bson tag is here
	// because the mongo backend writes snake_case keys explicitly.
	CreatedAt time.Time `json:"created_at" bson:"created_at"`
}

type WorkflowEdge struct {
	ID           string         `json:"id"`
	SourceID     string         `json:"source_id"`
	TargetID     string         `json:"target_id"`
	SourceHandle string         `json:"source_handle,omitempty"`
	TargetHandle string         `json:"target_handle,omitempty"`
	Config       map[string]any `json:"config" omitzero:"true"`
}

type WorkflowExportBundle struct {
	Workflow Workflow `json:"workflow"`
	Sources  []Source `json:"sources,omitempty" omitzero:"true"`
	Sinks    []Sink   `json:"sinks,omitempty" omitzero:"true"`

	// MissingRefs names the dependencies the workflow points at that no longer
	// exist on the exporting instance. They were previously dropped from the
	// bundle in silence, so an export of a workflow with a dangling reference
	// looked complete and imported into a workflow that could not start.
	MissingRefs []MissingRef `json:"missing_refs,omitempty" omitzero:"true"`
}

type WorkflowHealth struct {
	WorkflowID string        `json:"workflow_id"`
	Status     string        `json:"status"` // "healthy", "degraded", "error"
	Issues     []string      `json:"issues" omitzero:"true"`
	Uptime     time.Duration `json:"uptime"`
	Processed  uint64        `json:"processed"`
	Errors     uint64        `json:"errors"`
	Lag        uint64        `json:"lag"`
	MPS        float64       `json:"mps"`
	Latency    time.Duration `json:"latency"`
}

type WorkflowNode struct {
	ID        string         `json:"id"`
	Type      string         `json:"type"`             // source, sink, transformer, condition, etc.
	RefID     string         `json:"ref_id,omitempty"` // ID of the source, sink, or transformation
	Config    map[string]any `json:"config" omitzero:"true"`
	X         float64        `json:"x"`
	Y         float64        `json:"y"`
	UnitTests []UnitTest     `json:"unit_tests" omitzero:"true"`
}

type WorkflowTier string

type WorkflowVersion struct {
	ID             string         `json:"id"`
	WorkflowID     string         `json:"workflow_id"`
	Version        int            `json:"version"`
	Nodes          []WorkflowNode `json:"nodes"`
	Edges          []WorkflowEdge `json:"edges"`
	TraceRetention string         `json:"trace_retention,omitempty"`
	AuditRetention string         `json:"audit_retention,omitempty"`
	Config         string         `json:"config"` // JSON of other workflow settings
	CreatedAt      time.Time      `json:"created_at"`
	CreatedBy      string         `json:"created_by"`
	Message        string         `json:"message"` // commit message for the version
}

type Workspace struct {
	ID            string    `json:"id"`
	Name          string    `json:"name"`
	Description   string    `json:"description"`
	MaxWorkflows  int       `json:"max_workflows"`
	MaxCPU        float64   `json:"max_cpu"`
	MaxMemory     float64   `json:"max_memory"`
	MaxThroughput int       `json:"max_throughput"` // messages per second
	CreatedAt     time.Time `json:"created_at"`
}