store

type AwaitBinding struct {
	BindingID      string
	TaskID         string
	NodeName       string
	ProviderTaskID string // 外部 Provider 返回的 job_id / task_id
	Status         string // "awaiting" | "completed" | "failed"
	Input          map[string]any
	CreatedAt      time.Time
	ResolvedAt     time.Time // zero = 未完成
}

type AwaitStore interface {
	// CreateBinding 登记一个异步等待。
	// 调用时机：Scheduler 执行 async 节点，Begin 返回后。
	CreateBinding(ctx context.Context, binding AwaitBinding) error

	// ResolveBinding 原子完成一个等待。
	// 幂等保证：如果 binding 已经被其他线程 resolve，返回 (false, nil)。
	// 调用时机：外部 Notify / poll 到达。
	ResolveBinding(ctx context.Context, bindingID string) (claimed bool, err error)

	// FindByProviderTaskID 通过外部 Provider 返回的 task ID 查找 binding。
	// 调用时机：Notify handler 收到 providerTaskID，需要找到对应的 binding。
	// 无匹配时返回 nil, nil。
	FindByProviderTaskID(ctx context.Context, providerTaskID string) (*AwaitBinding, error)

	// ListPending 列出所有 awaiting 状态的 binding。
	// 用于 poll worker 定期扫描超时或需要轮询的 binding。
	ListPending(ctx context.Context) ([]AwaitBinding, error)

	// ListByTask 列出某个 Task 下的所有 binding。
	ListByTask(ctx context.Context, taskID string) ([]AwaitBinding, error)
}

type NodeRecord struct {
	NodeName string
	State    runtime.NodeState
	Output   map[string]any
	Error    string
}

type RunMeta struct {
	ID             string // 外部传入或自动生成
	ConversationID string // 调起此 workflow 的 Conversation（关联，非依赖）
	Goal           string // 用户目标 / Plan 的描述
	ToolCatalog    []ToolInfo
}

type Task struct {
	ID        string
	RunID     string
	ParentID  string
	RootID    string
	Status    string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type TaskMeta struct {
	ID       string
	ParentID string // 子 task 的父 task
	RootID   string // 根 task
}

type ToolInfo struct {
	Name        string
	Description string
	InputSchema []byte // JSON Schema
}

type TraceStore interface {
	// AppendTrace 追加一批 trace event。调用方可批量写入以降低 I/O。
	AppendTrace(ctx context.Context, taskID string, events []runtime.TraceEvent) error

	// ReplayTrace 从指定 Seq 起回放 trace event。用于恢复执行状态。
	// sinceSeq=0 表示从头回放。
	ReplayTrace(ctx context.Context, taskID string, sinceSeq int64) ([]runtime.TraceEvent, error)
}

type WorkflowRun struct {
	ID             string
	ConversationID string
	Goal           string
	Status         string // "running" | "completed" | "failed" | "suspended"
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

type WorkflowStore interface {

	// CreateRun 创建一个新的 Workflow 执行记录。
	CreateRun(ctx context.Context, meta RunMeta) (*WorkflowRun, error)

	// LoadRun 按 ID 加载 Workflow 执行记录。
	LoadRun(ctx context.Context, runID string) (*WorkflowRun, error)

	// UpdateRunStatus 更新 Workflow 运行状态。
	UpdateRunStatus(ctx context.Context, runID string, status string) error

	// CreateTask 创建一个新 Task（可能是一次 tool 调用批次）。
	CreateTask(ctx context.Context, runID string, meta TaskMeta) (*Task, error)

	// LoadTask 按 ID 加载 Task。
	LoadTask(ctx context.Context, taskID string) (*Task, error)

	// ListTasks 列出某个 Run 下的所有 Task。
	ListTasks(ctx context.Context, runID string) ([]Task, error)

	// PersistNode 持久化一个节点的状态和输出。幂等：重复写入同一 node 为 update。
	PersistNode(ctx context.Context, taskID string, nodeName string, state runtime.NodeState, output map[string]any) error

	// LoadNodeStates 加载某个 Task 下所有节点的状态。
	LoadNodeStates(ctx context.Context, taskID string) ([]NodeRecord, error)

	// SavePlan 保存 Plan 快照。用于 crash recovery 时恢复 Scheduler 状态。
	// nil plan 表示清除（任务已完成/失败）。
	SavePlan(ctx context.Context, taskID string, plan *runtime.Plan) error

	// LoadPlan 加载上次保存的 Plan 快照。无已保存 plan 时返回 nil。
	LoadPlan(ctx context.Context, taskID string) (*runtime.Plan, error)
}