ops

type AppendMetricsSessionOperation interface {
	Execute(ctx context.Context, vaultPath, taskName, sessionID string) error
}

type BackfillResult struct {
	// ModifiedFiles is the list of absolute file paths that were written during backfill.
	ModifiedFiles []string
	// SkippedFiles is the count of files skipped due to errors.
	SkippedFiles int
}

type ClaudeResumer interface {
	// ResumeSession replaces the current process with an interactive
	// claude --resume session.
	//
	// A non-empty prompt is appended to argv as the resumed session's first
	// interactive turn. An empty or whitespace-only prompt is omitted
	// entirely, so argv is identical to a plain `claude --resume <id>` —
	// callers that have nothing to say must not produce a trailing empty
	// positional argument.
	ResumeSession(ctx context.Context, sessionID string, cwd string, prompt string) error
}

type ClaudeSessionStarter interface {
	// StartSession runs claude in headless mode to create a session with the given
	// session id and returns only an error. The session id is minted by the caller
	// (not by claude) so it can be persisted before the child process exists.
	// When name is non-empty, the session is created with -n <name> so its
	// custom-title and agent-name are set from turn 1.
	// Both branches block until the headless turn completes and validate its JSON
	// result; they differ in how. The interactive branch runs the child under the
	// request context (bounded by a 5m timeout). The non-interactive branch spawns
	// the child detached from the request context and waits for its exit, bounded by
	// sessionTurnTimeout — a wait bound, not a kill. The turn is judged by its
	// validated result: a non-zero child exit is not itself a failure when the result
	// validates, and the caller persists no session id only when the turn genuinely
	// failed. That way the UI never offers Resume against a live or failed transcript.
	// See docs/work-on-session-lifecycle.md.
	StartSession(ctx context.Context, sessionID string, prompt string, cwd string, name string, isInteractive bool) error
}

type CompleteOperation interface {
	// Execute marks a task as complete. When force is true the incomplete-subtask
	// guard is bypassed, mirroring the --force flag on goal complete.
	// reason and gateSuccessor are the one-step close-out fields (aborted_reason /
	// gate_successor) and are persisted with the status in a single write when
	// non-empty; they are ignored for recurring tasks, whose status never changes.
	Execute(
		ctx context.Context,
		vaultPath string,
		taskName string,
		vaultName string,
		force bool,
		reason string,
		gateSuccessor string,
	) (MutationResult, error)
}

type DecisionAckOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		vaultName string,
		decisionName string,
		statusOverride string,
	) (MutationResult, error)
}

type DecisionListItem struct {
	Name         string `json:"name"`
	Reviewed     bool   `json:"reviewed"`
	ReviewedDate string `json:"reviewed_date,omitempty"`
	Status       string `json:"status,omitempty"`
	Type         string `json:"type,omitempty"`
	PageType     string `json:"page_type,omitempty"`
	Vault        string `json:"vault"`
}

type DecisionListOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		vaultName string,
		showReviewed bool,
		showAll bool,
	) ([]DecisionListItem, error)
}

type DeferOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		taskName string,
		dateStr string,
		vaultName string,
	) (MutationResult, error)
}

type EnsureAllTaskIdentifiersOperation interface {
	Execute(ctx context.Context, vaultPath string) (BackfillResult, error)
}

type EntityClearOperation interface {
	Execute(ctx context.Context, vaultPath, entityName, key string) error
}

type EntityGetOperation interface {
	Execute(ctx context.Context, vaultPath, entityName, key string) (string, error)
}

type EntityListAddOperation interface {
	Execute(ctx context.Context, vaultPath, entityName, field, value string) error
}

type EntityListRemoveOperation interface {
	Execute(ctx context.Context, vaultPath, entityName, field, value string) error
}

type EntitySetOperation interface {
	Execute(ctx context.Context, vaultPath, entityName, key, value, reason, gateSuccessor string) error
}

type EntityShowOperation interface {
	Execute(ctx context.Context, vaultPath, vaultName, entityName string) (EntityShowResult, error)
}

type EntityShowResult struct {
	Name       string            `json:"name"`
	FilePath   string            `json:"file_path"`
	Vault      string            `json:"vault"`
	Fields     map[string]string `json:"fields"`
	FieldOrder []string          `json:"field_order,omitempty"`
	Content    string            `json:"content"`
}

type Escalation struct {
	// TaskIdentifier is the task's task_identifier frontmatter value.
	TaskIdentifier string
	// TaskName is the task's filename without the .md extension.
	TaskName string
	// PreviousAssignee is the assignee value the task held before the clear.
	PreviousAssignee string
	// Status is the task's status after the clear, as the normalizing Status()
	// accessor reads it. Empty when the frontmatter carries no recognizable
	// status — the peer renders the same empty string in that case.
	Status string
	// Phase is the task's phase after the clear, or the empty string when the
	// frontmatter carries no phase. The peer renders an absent phase the same
	// way, so this is deliberately not defaulted to anything.
	Phase string
	// VaultName is the vault's configured name — the lowercased slug the peer's
	// VAULT_NAME carries — and is what the Obsidian link opens.
	VaultName string
	// TasksDir is the vault's configured tasks directory, joined with the task
	// name to form the vault-relative path the link points at.
	TasksDir string
}

type EscalationPublisher interface {
	PublishEscalation(ctx context.Context, escalation Escalation)
}

type FrontmatterClearOperation interface {
	Execute(ctx context.Context, vaultPath, taskName, key string) error
}

type FrontmatterEntity interface {
	GetField(key string) string
	SetField(ctx context.Context, key, value string) error
	ClearField(key string)
	Keys() []string
}

type FrontmatterGetOperation interface {
	Execute(ctx context.Context, vaultPath, taskName, key string) (string, error)
}

type FrontmatterSetOperation interface {
	// Execute sets one frontmatter field on a task.
	//
	// actor names who is performing the write. It is consulted only for the
	// "flag" key, where it is recorded as flag_set_by in the same write that sets
	// the flag; every other key ignores it. A truthy flag write with a blank
	// actor is refused with nothing written, because a present-but-blank
	// flag_set_by is worse than no record at all.
	Execute(ctx context.Context, vaultPath, taskName, key, value, reason, gateSuccessor, actor string, force bool) error
}

type GoalCompleteOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		goalName string,
		vaultName string,
		force bool,
		reason string,
		gateSuccessor string,
	) (MutationResult, error)
}

type GoalDeferOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		goalName string,
		dateStr string,
		vaultName string,
	) (MutationResult, error)
}

type GoalWorkOnOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		goalName string,
		assignee string,
		vaultName string,
		isInteractive bool,
		sessionDir string,
		vault *config.Vault,
	) (MutationResult, error)
}

type InteractionCounter interface {
	// Count returns the total number of type:"user" entries across the session JSONL
	// logs for the given session ids. Missing, unreadable, malformed, or unsafe session
	// ids contribute 0. It never returns an error and never blocks completion.
	Count(ctx context.Context, sessionIDs []string) int
}

type IssueType string

type LauncherFactory func(script string) (ClaudeSessionStarter, ClaudeResumer)

type LintIssue struct {
	FilePath    string
	IssueType   IssueType
	Description string
	Fixable     bool
	Fixed       bool
}

type LintIssueJSON struct {
	File        string `json:"file"`
	Type        string `json:"type"`
	Description string `json:"description"`
	Fixed       bool   `json:"fixed,omitempty"`
}

type LintOperation interface {
	Execute(
		ctx context.Context,
		pageType string,
		vaultPath string,
		tasksDir string,
		goalsDir string,
		fix bool,
	) ([]LintIssue, error)
	ExecuteFile(
		ctx context.Context,
		pageType string,
		filePath string,
		taskName string,
		vaultName string,
	) ([]LintIssue, error)
}

type ListOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		vaultName string,
		pagesDir string,
		statusFilters []string,
		showAll bool,
		assigneeFilter string,
		goalFilter string,
	) ([]TaskListItem, error)
}

type MutationResult struct {
	Success   bool     `json:"success"`
	Name      string   `json:"name,omitempty"`
	Vault     string   `json:"vault,omitempty"`
	Error     string   `json:"error,omitempty"`
	Warnings  []string `json:"warnings,omitempty"`
	SessionID string   `json:"session_id,omitempty"`
	Message   string   `json:"message,omitempty"`
	// Subtask blocking fields (used when a task cannot be completed due to incomplete subtasks)
	Reason     string `json:"reason,omitempty"`
	Pending    int    `json:"pending,omitempty"`
	InProgress int    `json:"inprogress,omitempty"`
	Completed  int    `json:"completed,omitempty"`
	Total      int    `json:"total,omitempty"`
}

type NotificationPublishCommandSender interface {
	SendPublishNotificationCommand(ctx context.Context, command notifcmd.NotificationPublishCommand) error
}

type NotificationSenderFactory interface {
	Create(ctx context.Context, brokers, topicPrefix string) (NotificationPublishCommandSender, error)
}

type ObjectiveCompleteOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		objectiveName string,
		vaultName string,
	) (MutationResult, error)
}

type RemoveMetricsSessionOperation interface {
	Execute(ctx context.Context, vaultPath, taskName, sessionID string) error
}

type ResolveOperation interface {
	Execute(ctx context.Context, vaultPath string, name string) (domain.ResolveResult, error)
}

type RollupBaseline struct {
	Captured      string               `json:"captured"`
	HumanTotal    int                  `json:"human_total"`
	Median        int                  `json:"median"`
	Weeks         map[string]int       `json:"weeks"`
	AgentCoverage string               `json:"agent_coverage"`
	Deltas        RollupBaselineDeltas `json:"deltas"`
}

type RollupBaselineDelta struct {
	Computed float64 `json:"computed"`
	Baseline float64 `json:"baseline"`
	Delta    float64 `json:"delta"`
	Mismatch bool    `json:"mismatch,omitempty"`
}

type RollupBaselineDeltas struct {
	HumanInteractions *RollupBaselineDelta `json:"human_interactions,omitempty"`
	PerFamilyMedian   *RollupBaselineDelta `json:"per_family_median,omitempty"`
}

type RollupFamily struct {
	Name   string `json:"name"`
	Median string `json:"median"`
}

type RollupWeeklyOperation interface {
	// Execute computes the rollup for one ISO week of one vault. week is the raw
	// --week token (YYYY-Wnn); an empty token means the last complete ISO week,
	// taken from the injected clock. vaultName is carried for error messages only.
	Execute(
		ctx context.Context,
		vaultPath string,
		vaultName string,
		week string,
	) (RollupWeeklyResult, error)
}

type RollupWeeklyResult struct {
	Year                 int             `json:"year"`
	Week                 int             `json:"week"`
	WeekStart            string          `json:"week_start"`
	WeekEnd              string          `json:"week_end"`
	HumanInteractions    string          `json:"human_interactions"`
	UnattendedDeliveries string          `json:"unattended_deliveries"`
	PerFamilyMedian      string          `json:"per_family_median"`
	Families             []RollupFamily  `json:"families"`
	Baseline             *RollupBaseline `json:"baseline,omitempty"`
}

type SearchOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		scopeDir string,
		query string,
		topK int,
	) ([]string, error)
}

type SessionLock interface {
	// Release releases the lock by closing the fd. Idempotent; the kernel also
	// releases it on process death, so Release is never strictly required.
	Release() error
	// File returns the underlying open file. FD_CLOEXEC is cleared on it so the
	// fd survives syscall.Exec on the interactive resume path (the resumed
	// claude holds the lock until it exits). Exposed for that exec-survival proof.
	File() *os.File
}

type SessionLocker interface {
	// Acquire takes the exclusive, non-blocking per-session lock for sessionID,
	// creating the lock directory on demand. On contention it fails immediately
	// and returns ErrSessionBusy (errors.Is true) wrapped with a message naming
	// the session id. The lock is held until Release or process death.
	Acquire(ctx context.Context, sessionID string) (SessionLock, error)
}

type ShowOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		vaultName string,
		taskName string,
	) (TaskDetail, error)
}

type TaskAnswerOperation interface {
	// Execute records the operator's answers into the named task's `Open
	// Questions` section, one answer per named item, and writes the task back in
	// a single write.
	//
	// Each answer names an item by its 1-based index and is rendered as
	// `<original marker and indentation><question text> → **<answer>**`, so the
	// file's own list style is preserved and each question keeps its answer on
	// the same line. Answering the same item again replaces the previous answer
	// rather than adding a second one, so the command is safe to re-run.
	//
	// Every other line — the frontmatter, the heading, the other sections, and
	// the items the caller did not answer — is left byte-identical. An index that
	// names no item in the section, and any answer for a task that has no such
	// section, is refused with nothing written; the error names the offending
	// index and the task.
	Execute(
		ctx context.Context,
		vaultPath string,
		taskName string,
		vaultName string,
		answers []domain.OpenAnswer,
	) (MutationResult, error)
}

type TaskApproveOperation interface {
	// Execute approves the named task: it moves a task waiting in the approval
	// inbox (phase todo) to phase planning and records, in the same write, who
	// approved it, the instant of the transition, and the task's owner. Any task
	// that is not waiting in the inbox, and any task that already carries an
	// approval record, is refused with nothing written.
	//
	// The owner is resolved once, at approval time, by precedence: assignee when
	// non-empty, else the task's existing assignee, else currentUser. An empty
	// assignee means the --assignee flag was not given (a blank flag value is
	// never a request for an unowned task); an empty currentUser means no current
	// user could be resolved. When none of the three names an owner the approval
	// is refused and nothing is written, so a task can never enter planning
	// ownerless. An existing assignee that neither the flag nor currentUser
	// matches is preserved untouched and silently.
	Execute(
		ctx context.Context,
		vaultPath string,
		taskName string,
		vaultName string,
		approvedBy string,
		assignee string,
		currentUser string,
	) (MutationResult, error)
}

type TaskDetail struct {
	Name            string   `json:"name"`
	Status          string   `json:"status"`
	Phase           string   `json:"phase,omitempty"`
	Assignee        string   `json:"assignee,omitempty"`
	Priority        int      `json:"priority,omitempty"`
	Category        string   `json:"category,omitempty"`
	Recurring       string   `json:"recurring,omitempty"`
	DeferDate       string   `json:"defer_date,omitempty"`
	PlannedDate     string   `json:"planned_date,omitempty"`
	DueDate         string   `json:"due_date,omitempty"`
	ClaudeSessionID string   `json:"claude_session_id,omitempty"`
	Goals           []string `json:"goals,omitempty"`
	Description     string   `json:"description,omitempty"`
	Content         string   `json:"content"`
	ModifiedDate    string   `json:"modified_date,omitempty"`
	CompletedDate   string   `json:"completed_date,omitempty"`
	FilePath        string   `json:"file_path"`
	Vault           string   `json:"vault"`
	Flag            bool     `json:"flag,omitempty"`
	FlagSetBy       string   `json:"flag_set_by,omitempty"`
	FlagSetAt       string   `json:"flag_set_at,omitempty"`
	// OpenQuestions lists the task's Open Questions section items in section
	// order. It is always non-nil so `--output json` emits `[]`, not `null`, for
	// a task with no such section.
	OpenQuestions []domain.OpenQuestion `json:"open_questions"`
}

type TaskListItem struct {
	Name            string   `json:"name"`
	Status          string   `json:"status"`
	Assignee        string   `json:"assignee,omitempty"`
	Priority        int      `json:"priority,omitempty"`
	Vault           string   `json:"vault"`
	Category        string   `json:"category,omitempty"`
	Recurring       string   `json:"recurring,omitempty"`
	DeferDate       string   `json:"defer_date,omitempty"`
	PlannedDate     string   `json:"planned_date,omitempty"`
	DueDate         string   `json:"due_date,omitempty"`
	ClaudeSessionID string   `json:"claude_session_id,omitempty"`
	Phase           string   `json:"phase,omitempty"`
	ModifiedDate    string   `json:"modified_date,omitempty"`
	CompletedDate   string   `json:"completed_date,omitempty"`
	Goals           []string `json:"goals,omitempty"`
	Flag            bool     `json:"flag,omitempty"`
	FlagSetBy       string   `json:"flag_set_by,omitempty"`
	FlagSetAt       string   `json:"flag_set_at,omitempty"`
	BlockedBy       []string `json:"blocked_by,omitempty"`
	Blocked         *bool    `json:"blocked,omitempty"`
}

type TopicCompleteOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		topicName string,
		vaultName string,
	) (MutationResult, error)
}

type TopicDeferOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		topicName string,
		dateStr string,
		vaultName string,
	) (MutationResult, error)
}

type TopicWorkOnOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		topicName string,
		assignee string,
		vaultName string,
		isInteractive bool,
		sessionDir string,
		vault *config.Vault,
	) (MutationResult, error)
}

type UpdateOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		taskName string,
		vaultName string,
	) (MutationResult, error)
}

type ValidateIssueJSON struct {
	Type        string `json:"type"`
	IssueType   string `json:"issue_type"`
	Description string `json:"description"`
}

type ValidateResult struct {
	Name   string              `json:"name"`
	Vault  string              `json:"vault"`
	Issues []ValidateIssueJSON `json:"issues"`
}

type VaultDispatcher interface {
	FirstSuccess(
		ctx context.Context,
		vaults []*config.Vault,
		fn func(vault *config.Vault) error,
	) error
}

type WatchDir struct {
	Dir  string
	Kind string
}

type WatchEvent struct {
	Event string `json:"event"`
	Name  string `json:"name"`
	Vault string `json:"vault"`
	Path  string `json:"path"`
	Type  string `json:"type"`
}

type WatchOperation interface {
	Execute(ctx context.Context, vaults []WatchTarget, handler func(WatchEvent) error) error
}

type WatchTarget struct {
	VaultPath string
	VaultName string
	WatchDirs []WatchDir
}

type WorkOnOperation interface {
	Execute(
		ctx context.Context,
		vaultPath string,
		taskName string,
		assignee string,
		vaultName string,
		isInteractive bool,
		sessionDir string,
		vault *config.Vault,
	) (MutationResult, error)
}