trigger

type BoardEffect interface {
	Promote(ctx context.Context, plan LaunchPlan) (issueID string, err error)
}

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

type BoardSourceOption func(*BoardSource)

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

type EvaluatorOption func(*Evaluator)

type Event struct {
	// ID is a stable per-event identifier used for idempotency/dedup
	// (e.g. "board:<board>:<issue>:<seq>"). A source that has no natural
	// key generates a ULID/uuid.
	ID     string `json:"id" bson:"_id"`
	Source Source `json:"source" bson:"source"`
	// Kind is the source-specific event type (forge event name, board
	// card.* kind, "run_finished", "cron", ...).
	Kind string `json:"kind" bson:"kind"`
	// Action narrows Kind where the source has one (forge "opened"/"reopened").
	Action string `json:"action,omitempty" bson:"action,omitempty"`
	// TenantID scopes the event to an org in cloud mode; "" in local single-host.
	TenantID string `json:"tenant_id,omitempty" bson:"tenant_id,omitempty"`
	// Repo is the forge slug ("group/project") or the local repo root the
	// event pertains to; "" for tenant-wide events.
	Repo    string  `json:"repo,omitempty" bson:"repo,omitempty"`
	Subject Subject `json:"subject" bson:"subject"`
	// Actor is the triggering identity (PR author login, commenter, "schedule").
	Actor string `json:"actor,omitempty" bson:"actor,omitempty"`
	// Labels are the labels on the subject at event time (board card labels,
	// issue labels). Matched by Matcher.Labels.
	Labels []string `json:"labels,omitempty" bson:"labels,omitempty"`
	// Payload carries source-specific extras used for var templating
	// (issue title/body, comment args, board from/to state, ...).
	Payload    map[string]any `json:"payload,omitempty" bson:"payload,omitempty"`
	OccurredAt time.Time      `json:"occurred_at" bson:"occurred_at"`
}

type LabelConsumer interface {
	ConsumeMatchLabels(ctx context.Context, tenantID, issueID string, labels []string) (consumed bool, err error)
}

type LaunchPlan struct {
	BotID    string
	TenantID string
	Repo     string
	Mode     bundle.ExecutionMode
	// Vars are the fully-resolved launch vars (subscription Vars + the
	// ArgsVar payload), ready to stamp on the run / card.
	Vars            map[string]string
	KeyOverrides    map[string]string
	SecretOverrides map[string]string
	// RepoURL/RepoRef target a cloud clone when the event carries them.
	RepoURL string
	RepoRef string
	// Event is the originating event (provenance, run→source back-link).
	Event Event
	// SourceRef, when non-nil, stamps typed provenance on the launched
	// run (runview.LaunchSpec.SourceRef → run.json source). The
	// Scheduler populates it for schedule fires so the schedgate
	// overlap gate can count this schedule's live runs; other paths
	// leave it nil.
	SourceRef *store.RunSource
}

type Launcher interface {
	Launch(ctx context.Context, plan LaunchPlan) (runID string, err error)
}

type Matcher struct {
	Sources       []Source `json:"sources,omitempty" bson:"sources,omitempty"`
	Kinds         []string `json:"kinds,omitempty" bson:"kinds,omitempty"`
	Actions       []string `json:"actions,omitempty" bson:"actions,omitempty"`
	Repos         []string `json:"repos,omitempty" bson:"repos,omitempty"`
	Authors       []string `json:"authors,omitempty" bson:"authors,omitempty"`
	Labels        []string `json:"labels,omitempty" bson:"labels,omitempty"`
	SubjectStates []string `json:"subject_states,omitempty" bson:"subject_states,omitempty"`
}

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

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

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

type Nudger interface {
	Refresh()
}

type Publisher interface {
	Publish(ctx context.Context, ev Event) error
}

type ScheduleGate struct {
	Lister   schedgate.ScheduleRunLister
	Audit    func(schedgate.TickRecord)
	GuardDir string
	// Reap cancels keepalive runs found stale at a tick (so the zombie
	// frees resources once a fresh run has relaunched). Nil is safe — the
	// stale run simply lingers but no longer blocks relaunch.
	Reap func(ctx context.Context, runIDs []string)
}

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

type SchedulerOption func(*Scheduler)

type SchedulerStatus struct {
	// LastTickAt is when tick() last ran (zero before the first tick).
	LastTickAt time.Time `json:"last_tick_at"`
	// Subscriptions is the schedule-kind subscription count seen on the
	// last tick.
	Subscriptions int `json:"subscriptions"`
	// Armed is how many subscriptions currently hold a next-fire slot.
	Armed int `json:"armed"`
	// IntervalSeconds is the tick cadence, so a reader can judge
	// staleness ("last tick 3 intervals ago = dead").
	IntervalSeconds float64 `json:"interval_seconds"`
}

type Source string

type Subject struct {
	Type  string `json:"type" bson:"type"` // "pull_request" | "issue" | "card" | "run" | "repo" | "comment"
	ID    string `json:"id,omitempty" bson:"id,omitempty"`
	URL   string `json:"url,omitempty" bson:"url,omitempty"`
	SHA   string `json:"sha,omitempty" bson:"sha,omitempty"`
	Ref   string `json:"ref,omitempty" bson:"ref,omitempty"`
	Title string `json:"title,omitempty" bson:"title,omitempty"`
	Body  string `json:"body,omitempty" bson:"body,omitempty"`
	// State is the subject's workflow/board state at the time of the event
	// (e.g. the board column a card entered). Matched by Matcher.SubjectStates.
	State string `json:"state,omitempty" bson:"state,omitempty"`
}

type Subscription struct {
	ID       string `json:"id" bson:"_id"`
	TenantID string `json:"tenant_id,omitempty" bson:"tenant_id,omitempty"`
	// Repo scopes the subscription to one repo ("group/project"); "" makes it
	// tenant-wide (e.g. a board-wide trigger on the local single-host board).
	Repo  string `json:"repo,omitempty" bson:"repo,omitempty"`
	BotID string `json:"bot_id" bson:"bot_id"`
	// Invocation names which bot capability this subscription activates, so a
	// deprovision/regeneration can rebuild exactly the rows derived from a
	// given invocation kind.
	Invocation bundle.InvocationKind `json:"invocation" bson:"invocation"`
	// Mode is direct (launch now) vs board (materialise a card the dispatcher
	// claims). Empty inherits the invocation's EffectiveMode at evaluation.
	Mode  bundle.ExecutionMode `json:"mode,omitempty" bson:"mode,omitempty"`
	Match Matcher              `json:"match" bson:"match"`
	// ConsumeLabels (board-source, direct-mode only) strips the Match.Labels
	// set from the card before launching, making the labels a one-shot
	// trigger: duplicate card events can't double-launch, and re-adding the
	// label re-arms it. Mirrors bundle.InvocationBoard.ConsumeLabels.
	ConsumeLabels bool `json:"consume_labels,omitempty" bson:"consume_labels,omitempty"`
	// Vars are launch-var overrides stamped on the run (ContextVars +
	// operator LaunchVars merged at provision time; operator wins).
	Vars map[string]string `json:"vars,omitempty" bson:"vars,omitempty"`
	// ArgsVar names the workflow input var that receives the event's free-text
	// payload (issue title+body, comment args). Empty injects no payload.
	ArgsVar string `json:"args_var,omitempty" bson:"args_var,omitempty"`
	// Cron is set only for Invocation == schedule (the timer source matches it).
	Cron string `json:"cron,omitempty" bson:"cron,omitempty"`
	// IntervalSeconds is set only for Invocation == keepalive (the sub-minute
	// counterpart of Cron): the always-on relaunch cadence in seconds.
	IntervalSeconds int               `json:"interval_seconds,omitempty" bson:"interval_seconds,omitempty"`
	KeyOverrides    map[string]string `json:"key_overrides,omitempty" bson:"key_overrides,omitempty"`
	SecretOverrides map[string]string `json:"secret_overrides,omitempty" bson:"secret_overrides,omitempty"`
	// Overlap policy + pre-launch guard for schedule-kind subscriptions
	// (pkg/schedgate). Overlap "" normalizes to "skip": a cron tick
	// whose previous run is still live is skipped and audited instead
	// of piling up. Guard is an optional `sh -lc` gate: exit 0 fires
	// (stdout → vars[GuardVar]), non-zero skips the tick.
	Overlap       string `json:"overlap,omitempty" bson:"overlap,omitempty"`
	MaxConcurrent int    `json:"max_concurrent,omitempty" bson:"max_concurrent,omitempty"`
	Guard         string `json:"guard,omitempty" bson:"guard,omitempty"`
	GuardTimeout  string `json:"guard_timeout,omitempty" bson:"guard_timeout,omitempty"`
	GuardVar      string `json:"guard_var,omitempty" bson:"guard_var,omitempty"`
	// StaleAfter is the keepalive silence cutoff (Go duration); empty
	// normalizes to schedgate.DefaultStaleAfter. Only meaningful with
	// Overlap == keepalive.
	StaleAfter string `json:"stale_after,omitempty" bson:"stale_after,omitempty"`
	// Origin records where this subscription came from so dedup and cleanup
	// are possible: "forge:<repo_integration_id>" (orchestrator-generated,
	// deleted by Origin on deprovision), "operator" (studio), "schedule.yaml"
	// / "dispatcher.yaml" (local config load).
	Origin    string    `json:"origin,omitempty" bson:"origin,omitempty"`
	Enabled   bool      `json:"enabled" bson:"enabled"`
	CreatedBy string    `json:"created_by,omitempty" bson:"created_by,omitempty"`
	CreatedAt time.Time `json:"created_at" bson:"created_at"`
	UpdatedAt time.Time `json:"updated_at" bson:"updated_at"`
}

type SubscriptionStore interface {
	Create(ctx context.Context, s Subscription) error
	Get(ctx context.Context, id string) (Subscription, error)
	Update(ctx context.Context, s Subscription) error
	Delete(ctx context.Context, id string) error

	// ListByTenant returns every subscription owned by a tenant
	// ("" tenant = the local single-host scope).
	ListByTenant(ctx context.Context, tenantID string) ([]Subscription, error)
	// ListByRepo returns subscriptions scoped to a specific repo plus the
	// tenant-wide (Repo == "") ones, since both can fire for a repo event.
	ListByRepo(ctx context.Context, tenantID, repo string) ([]Subscription, error)
	// ListByBot returns every subscription that launches a given bot.
	ListByBot(ctx context.Context, tenantID, botID string) ([]Subscription, error)
	// ListByOrigin returns subscriptions provisioned under an Origin marker
	// (e.g. "forge:<repo_integration_id>") so a deprovision can delete exactly
	// the rows it created.
	ListByOrigin(ctx context.Context, tenantID, origin string) ([]Subscription, error)
	// ListCandidates returns the enabled subscriptions that COULD match ev:
	// same tenant, and Repo matching ev.Repo or tenant-wide. The Evaluator
	// applies the full Matcher.Match on the returned set — this is only the
	// indexed pre-filter, kept coarse so it stays a single-index query.
	ListCandidates(ctx context.Context, ev Event) ([]Subscription, error)
}