client

type ActivityTask struct {
	TaskToken             []byte
	WorkflowID            string
	RunID                 string
	ActivityID            string
	ActivityTypeName      string
	Input                 []byte
	ScheduledTimeMs       int64
	StartToCloseTimeoutMs int64
	HeartbeatTimeoutMs    int64
}

type CheckHealthRequest struct{}

type CheckHealthResponse struct {
	// Service is the opaque backend identifier ("hanzo-tasks").
	Service string `json:"service"`
	// Status is "ok" when the frontend is healthy, anything else on
	// degradation.
	Status string `json:"status"`
}

type Client interface {
	// ExecuteWorkflow starts a workflow (by type name when `workflow`
	// is a string, or by reflected name when it is a Go function).
	// Returns a handle whose Get blocks until the workflow terminates.
	ExecuteWorkflow(
		ctx context.Context,
		opts StartWorkflowOptions,
		workflow any,
		args ...any,
	) (WorkflowRun, error)

	// SignalWorkflow posts a signal to a running execution.
	SignalWorkflow(
		ctx context.Context,
		workflowID, runID, signalName string,
		arg any,
	) error

	// SignalWithStartWorkflow atomically delivers a signal to the
	// workflow identified by workflowID, starting it with the
	// supplied opts+workflow+args if no matching execution is
	// running. Opcode 0x0066.
	SignalWithStartWorkflow(
		ctx context.Context,
		workflowID, signalName string,
		signalArg any,
		opts StartWorkflowOptions,
		workflow any,
		workflowArgs ...any,
	) (WorkflowRun, error)

	// GetWorkflow returns a handle to an already-started workflow.
	// No RPC is issued; subsequent Get / GetWithOptions calls on the
	// handle poll DescribeWorkflow to observe terminal state.
	GetWorkflow(ctx context.Context, workflowID, runID string) WorkflowRun

	// QueryWorkflow runs a registered query on a (possibly running)
	// workflow execution and returns the query's encoded result.
	// Opcode 0x0067. Queries are read-only — they do not mutate
	// workflow history.
	QueryWorkflow(
		ctx context.Context,
		workflowID, runID, queryType string,
		args ...any,
	) (converter.EncodedValue, error)

	// CancelWorkflow asks the server to cancel an execution.
	CancelWorkflow(ctx context.Context, workflowID, runID string) error

	// TerminateWorkflow force-stops an execution with a reason.
	TerminateWorkflow(ctx context.Context, workflowID, runID, reason string) error

	// DescribeWorkflow returns the current info record.
	DescribeWorkflow(ctx context.Context, workflowID, runID string) (*WorkflowExecutionInfo, error)

	// ListWorkflows runs a visibility query.
	ListWorkflows(ctx context.Context, query string, pageSize int32, nextPageToken []byte) (*ListWorkflowsResponse, error)

	// RegisterNamespace creates a new namespace on the server.
	RegisterNamespace(ctx context.Context, req *RegisterNamespaceRequest) error
	// DescribeNamespace returns a namespace's info + config.
	DescribeNamespace(ctx context.Context, name string) (*Namespace, error)
	// ListNamespaces pages through registered namespaces.
	ListNamespaces(ctx context.Context, pageSize int32, nextPageToken []byte) (*ListNamespacesResponse, error)

	// CreateSchedule registers a recurring schedule.
	CreateSchedule(ctx context.Context, opts CreateScheduleOptions) error
	// ListSchedules pages through schedules.
	ListSchedules(ctx context.Context, pageSize int32, nextPageToken []byte) (*ListSchedulesResponse, error)
	// DeleteSchedule removes a schedule by ID.
	DeleteSchedule(ctx context.Context, scheduleID string) error
	// PauseSchedule toggles a schedule's paused flag.
	PauseSchedule(ctx context.Context, scheduleID string, paused bool) error

	// Health reports server reachability as two flat strings.
	Health(ctx context.Context) (service, status string, err error)

	// CheckHealth is the structured counterpart to Health, matching
	// the upstream client shape so callers migrating from
	// go.temporal.io/sdk/client compile unchanged. A nil req is
	// treated as an empty request. Backed by the same opcode
	// 0x0090 as Health.
	CheckHealth(ctx context.Context, req *CheckHealthRequest) (*CheckHealthResponse, error)

	// Close releases the underlying ZAP connection.
	Close()
}

type CreateScheduleOptions struct {
	ID string

	// Spec: use either Cron expressions OR a single Interval.
	CronExpressions []string
	Interval        time.Duration
	StartTime       time.Time
	EndTime         time.Time
	Jitter          time.Duration
	Timezone        string

	// Action: the workflow to start on each tick.
	WorkflowID   string
	WorkflowType string
	TaskQueue    string
	Input        []any

	Paused bool
}

type ListNamespacesResponse struct {
	Namespaces    []Namespace `json:"namespaces"`
	NextPageToken []byte      `json:"next_page_token,omitempty"`
}

type ListSchedulesResponse struct {
	Schedules     []Schedule `json:"schedules"`
	NextPageToken []byte     `json:"next_page_token,omitempty"`
}

type ListWorkflowsResponse struct {
	Executions    []WorkflowExecutionInfo `json:"executions"`
	NextPageToken []byte                  `json:"next_page_token,omitempty"`
}

type Namespace struct {
	Info   NamespaceInfo   `json:"info"`
	Config NamespaceConfig `json:"config"`
}

type NamespaceConfig struct {
	Retention time.Duration `json:"-"`
}

type NamespaceInfo struct {
	Name        string         `json:"name"`
	State       NamespaceState `json:"state"`
	Description string         `json:"description,omitempty"`
	OwnerEmail  string         `json:"owner_email,omitempty"`
	ID          string         `json:"id,omitempty"`
}

type NamespaceState int8

type Options struct {
	// HostPort is the "host:port" address of the Hanzo Tasks frontend
	// exposing the ZAP transport (default port 9652).
	HostPort string

	// Namespace scopes every RPC issued by the returned Client. Empty
	// string is rewritten to "default" at Dial time.
	Namespace string

	// Identity is sent as the caller identity on long-poll / worker RPCs.
	// Optional; defaults to "hanzo-tasks-sdk".
	Identity string

	// DialTimeout bounds the initial ZAP connect. Zero means "no bound".
	DialTimeout time.Duration

	// CallTimeout bounds a single request/response round trip. Zero
	// means "no bound per call" — callers are expected to pass their
	// own ctx deadline.
	CallTimeout time.Duration

	// Transport overrides the default ZAP transport. Primarily for
	// testing — leave nil in production.
	Transport Transport
}

type PollActivityTaskRequest struct {
	Namespace     string
	TaskQueueName string
	TaskQueueKind int8
	Identity      string
}

type PollWorkflowTaskRequest struct {
	Namespace     string
	TaskQueueName string
	TaskQueueKind int8
	Identity      string
	WorkerBuildID string
}

type RecordActivityTaskHeartbeatRequest struct {
	TaskToken []byte
	Details   []byte
}

type RegisterNamespaceRequest struct {
	Name        string        `json:"name"`
	Description string        `json:"description,omitempty"`
	OwnerEmail  string        `json:"owner_email,omitempty"`
	Retention   time.Duration `json:"-"`
}

type RespondActivityTaskCompletedRequest struct {
	TaskToken []byte
	Result    []byte
}

type RespondActivityTaskFailedRequest struct {
	TaskToken []byte
	Failure   []byte
}

type RespondWorkflowTaskCompletedRequest struct {
	TaskToken []byte
	Commands  []byte
}

type RetryPolicyJSON struct {
	InitialIntervalMs      int64    `json:"initial_interval_ms,omitempty"`
	BackoffCoefficient     float64  `json:"backoff_coefficient,omitempty"`
	MaximumIntervalMs      int64    `json:"maximum_interval_ms,omitempty"`
	MaximumAttempts        int32    `json:"maximum_attempts,omitempty"`
	NonRetryableErrorTypes []string `json:"non_retryable_error_types,omitempty"`
}

type Schedule struct {
	ID     string         `json:"id"`
	Spec   ScheduleSpec   `json:"spec"`
	Action ScheduleAction `json:"action"`
	Paused bool           `json:"paused,omitempty"`
}

type ScheduleAction struct {
	WorkflowID   string `json:"workflow_id,omitempty"`
	WorkflowType string `json:"workflow_type"`
	TaskQueue    string `json:"task_queue"`
	Input        []any  `json:"input,omitempty"`
}

type ScheduleActivityRequest struct {
	Namespace      string
	WorkflowID     string
	RunID          string
	TaskQueue      string
	ActivityType   string
	Input          []byte
	StartToCloseMs int64
	HeartbeatMs    int64
	RetryPolicy    *RetryPolicyJSON
}

type ScheduleActivityResponse struct {
	ActivityTaskID string
	// TaskToken is the server-minted, HMAC-signed opaque token the
	// worker must present on RespondActivityTaskCompleted/Failed. Empty
	// on error, populated on success.
	TaskToken []byte
}

type ScheduleSpec struct {
	Cron      []string      `json:"-"`
	Interval  time.Duration `json:"-"`
	StartTime time.Time     `json:"-"`
	EndTime   time.Time     `json:"-"`
	Jitter    time.Duration `json:"-"`
	Timezone  string        `json:"-"`
}

type StartChildWorkflowRequest struct {
	Namespace    string
	ParentID     string
	ParentRunID  string
	WorkflowID   string
	WorkflowType string
	TaskQueue    string
	Input        []any
	RetryPolicy  *RetryPolicyJSON
	TimeoutsMs   TimeoutsJSON
}

type StartChildWorkflowResponse struct {
	RunID string
}

type StartWorkflowOptions struct {
	// ID is the workflow ID. Empty string asks the server to generate
	// one (returned as WorkflowRun.GetID()).
	ID string

	// TaskQueue is required; workers poll this queue for tasks.
	TaskQueue string

	// WorkflowExecutionTimeout is the total allowed wall-clock time
	// across all runs (Continue-As-New chains).
	WorkflowExecutionTimeout time.Duration

	// WorkflowRunTimeout is the allowed wall-clock time for a single
	// run.
	WorkflowRunTimeout time.Duration

	// WorkflowTaskTimeout bounds a single workflow-task attempt on a
	// worker. Default on server is 10s.
	WorkflowTaskTimeout time.Duration

	// RetryPolicy overrides the workflow-level retry policy (distinct
	// from per-activity retry).
	RetryPolicy *temporal.RetryPolicy

	// CronSchedule makes the workflow recurring. Empty string runs once.
	CronSchedule string

	// Memo is opaque metadata attached to the execution.
	Memo map[string]any

	// SearchAttributes are indexed by the visibility store.
	SearchAttributes map[string]any
}

type TimeoutsJSON struct {
	WorkflowExecutionMs int64 `json:"workflow_execution_ms,omitempty"`
	WorkflowRunMs       int64 `json:"workflow_run_ms,omitempty"`
	WorkflowTaskMs      int64 `json:"workflow_task_ms,omitempty"`
}

type Transport interface {
	// Call issues a single request for opcode and returns the
	// response frame.
	Call(ctx context.Context, opcode uint16, body []byte) (respFrame []byte, err error)

	// Close releases transport resources.
	Close() error
}

type WaitActivityResultRequest struct {
	ActivityTaskID string
	WaitMs         int64
}

type WaitActivityResultResponse struct {
	Ready   bool
	Result  []byte
	Failure []byte
}

type WorkerTransport interface {
	// Close tears down the underlying node. Safe to call more than
	// once.
	Close() error

	// PollWorkflowTask issues a long-poll for the next workflow
	// task on the given queue. The ctx carries the long-poll
	// deadline; returning a nil task and nil error signals "idle,
	// try again".
	PollWorkflowTask(ctx context.Context, req PollWorkflowTaskRequest) (*WorkflowTask, error)

	// PollActivityTask is the activity counterpart of
	// PollWorkflowTask. Same idle semantics.
	PollActivityTask(ctx context.Context, req PollActivityTaskRequest) (*ActivityTask, error)

	// RespondWorkflowTaskCompleted uploads the worker's commands
	// (encoded command list) for a workflow task.
	RespondWorkflowTaskCompleted(ctx context.Context, req RespondWorkflowTaskCompletedRequest) error

	// RespondActivityTaskCompleted reports a successful activity
	// result.
	RespondActivityTaskCompleted(ctx context.Context, req RespondActivityTaskCompletedRequest) error

	// RespondActivityTaskFailed reports an activity failure.
	RespondActivityTaskFailed(ctx context.Context, req RespondActivityTaskFailedRequest) error

	// RecordActivityTaskHeartbeat signals liveness for a long-running
	// activity. Returns cancelRequested=true if the server wants
	// the activity to stop.
	RecordActivityTaskHeartbeat(ctx context.Context, req RecordActivityTaskHeartbeatRequest) (bool, error)

	// ScheduleActivity asks the frontend to mint an activity task for
	// the given type + input and return a stable id (schema/tasks.zap
	// opcode 0x006B). The workerEnv in pkg/sdk/worker uses this from
	// inside a workflow to dispatch activities without racing the
	// worker's own pollActivityTask loop.
	ScheduleActivity(ctx context.Context, req ScheduleActivityRequest) (*ScheduleActivityResponse, error)

	// WaitActivityResult long-polls for the result of an activity id
	// previously returned by ScheduleActivity (opcode 0x006C). A
	// response with ready=false means "still pending" — the caller
	// re-issues. The ctx deadline bounds a single round-trip.
	WaitActivityResult(ctx context.Context, req WaitActivityResultRequest) (*WaitActivityResultResponse, error)

	// StartChildWorkflow asks the server to start a workflow whose
	// parent is recorded for linkage (opcode 0x006D). Returns the
	// run id; Phase-1 does not wait for child completion — the
	// caller uses DescribeWorkflow or a follow-up
	// WaitChildWorkflowResult when Phase-2 lands.
	StartChildWorkflow(ctx context.Context, req StartChildWorkflowRequest) (*StartChildWorkflowResponse, error)
}

type WorkflowExecutionInfo struct {
	WorkflowID    string         `json:"workflow_id"`
	RunID         string         `json:"run_id"`
	WorkflowType  string         `json:"workflow_type"`
	StartTime     time.Time      `json:"start_time,omitempty"`
	CloseTime     time.Time      `json:"close_time,omitempty"`
	Status        WorkflowStatus `json:"status"`
	HistoryLength int64          `json:"history_length"`
	TaskQueue     string         `json:"task_queue,omitempty"`
	Memo          map[string]any `json:"memo,omitempty"`
}

type WorkflowRun interface {
	// Get blocks until the workflow terminates and decodes the
	// result into valuePtr. When the workflow continues-as-new the
	// default behaviour follows the chain to the final run.
	Get(ctx context.Context, valuePtr any) error

	// GetWithOptions is the option-parameterised form of Get. When
	// opts.DisableFollowingRuns is true, Get stops at the current
	// run rather than following a continue-as-new chain to the final
	// run.
	GetWithOptions(ctx context.Context, valuePtr any, opts WorkflowRunGetOptions) error

	GetID() string
	GetRunID() string
}

type WorkflowRunGetOptions struct {
	// DisableFollowingRuns, when true, prevents Get from walking
	// the continue-as-new chain. It returns when the current run
	// terminates even if a successor run was started.
	DisableFollowingRuns bool
}

type WorkflowStatus int8

type WorkflowTask struct {
	TaskToken        []byte
	WorkflowID       string
	RunID            string
	WorkflowTypeName string
	History          []byte
	NextPageToken    []byte
}