task

type ApiConfig struct {
	// Bus is the host's app.BusI. nil substitutes a NoopBus that
	// errors on every call.
	Bus app.BusI

	// AppId is the owner identity injected into SpawnOpts.OwnerAppId.
	AppId app.AppIdT

	// InstanceKey is the host-minted per-window instance id injected
	// into SpawnOpts.OwnerTileKey.
	InstanceKey uint64

	// RunId is the process-wide run id injected into
	// SpawnOpts.OwnerRunId.
	RunId string

	// Logger is the base producer-side logger. The API adds task_id
	// before passing to each handle. Zero value writes nowhere.
	Logger zerolog.Logger

	// MountCancel is the app's mount-cancel channel. When non-nil, the
	// API composes it into every spawned task's parent context so
	// window close cascades into worker cancellation.
	MountCancel <-chan struct{}

	// ListTimeoutMs caps the bus.Request timeout for ListInflight.
	// Defaults to DefaultListTimeoutMs (2000ms) when zero.
	ListTimeoutMs int64
}

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

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

type HandleI interface {
	// Id returns the task identifier — same value as appears in subject
	// paths task.<id>.<verb>.
	Id() (id TaskIdT)

	// Ctx returns a context.Context that cancels when:
	//   - the parent context passed to Spawn cancels;
	//   - a task.<id>.cancel message arrives on the bus;
	//   - the handle reaches a terminal state (Done/Error).
	// Worker loops poll Ctx().Done() (or call Cancelled() as a
	// convenience) and exit promptly.
	Ctx() (ctx context.Context)

	// Cancelled is a shorthand for Ctx().Err() != nil.
	Cancelled() (b bool)

	// Report submits a progress sample. Publication is gated by the
	// estimator's humanized-change rule plus a 1 Hz heartbeat for
	// indeterminate tasks; callers should not rate-limit upstream.
	Report(p ProgressReport)

	// Note submits a text-only progress update. Same emission gate as
	// Report; useful for tasks whose progress is qualitative
	// ("connecting…", "negotiating tls…").
	Note(note string)

	// Done publishes the terminal-success message with an opaque result.
	// Pass nil result for tasks whose outcome is the side effect itself
	// (a file was written, a row was inserted). Idempotent.
	Done(result []byte) (err error)

	// Error publishes the terminal-failure message. err is encoded via
	// the boxer eh.MarshalError chain so errorview renders it directly;
	// reason is a short human label that surfaces in observer lists.
	// Idempotent.
	Error(err error, reason string) (rerr error)
}

type InflightSnapshotEntry struct {
	Id          TaskIdT    `json:"id"`
	Kind        string     `json:"kind"`
	Title       string     `json:"title,omitempty"`
	OwnerAppId  app.AppIdT `json:"ownerAppId,omitempty"`
	State       string     `json:"state"`
	CreatedAtMs int64      `json:"createdAtMs"`
	LastEmitMs  int64      `json:"lastEmitMs"`
	Current     uint64     `json:"current,omitempty"`
	Total       uint64     `json:"total,omitempty"`
	Unit        string     `json:"unit,omitempty"`
	EtaMs       int64      `json:"etaMs,omitempty"`
}

type InflightSnapshotReply struct {
	Entries []InflightSnapshotEntry `json:"entries"`
	AtMs    int64                   `json:"atMs"`
}

type NoopTaskApi struct{}

type ObserverI interface {
	OnCreated(c taskcreated.TaskCreated)
	OnProgress(p taskprogress.TaskProgress)
	OnDone(d taskdone.TaskDone)
	OnError(e taskerror.TaskError)
	OnCancel(c taskcancel.TaskCancel)
}

type ProgressReport struct {
	Current uint64
	Total   uint64
	Unit    UnitE
	Note    string
}

type SpawnOpts struct {
	// Id sets a deterministic task id. Empty means "generate one via
	// nanoid".
	Id TaskIdT

	// Kind groups tasks for observer dispatch ("ch.export", "fs.scan",
	// "kafka.catchup"). Required. Conventional strings, not a registered
	// enum.
	Kind string

	// Title is the human-readable label observers display. Defaults to
	// Kind when empty.
	Title string

	// OwnerAppId attributes the task to the spawning app. Carried in the
	// TaskCreated payload for audit and display; not validated. Empty is
	// allowed for runtime-side tasks that don't correspond to a user app.
	// Auto-filled by task.ForApp(ctx) — direct callers of Spawn
	// supply it themselves.
	OwnerAppId app.AppIdT

	// OwnerTileKey is the host-minted per-window instance id. Auto-filled
	// by task.ForApp(ctx) so audit rows can join back to
	// AppLifecycleRow.TileKey. Direct callers may leave it zero.
	OwnerTileKey uint64

	// OwnerRunId is the process-wide run id. Auto-filled by
	// task.ForApp(ctx) so audit rows can join back to
	// RuntimeStartRow.RunId. Direct callers may leave it empty.
	OwnerRunId string

	// Cancellable surfaces a hint to consumers (UI: should we show a
	// cancel button?). The handle's cancel subscription is always
	// active; this field controls observer affordances, not engine
	// behaviour.
	Cancellable bool

	// EstimatedMs gives an initial duration guess for observers (e.g.,
	// to show a progress bar before the first Report). Zero means
	// "unknown".
	EstimatedMs int64

	// HeartbeatMs overrides DefaultIndeterminateHeartbeatMs for tasks
	// whose total is unknown. Zero ⇒ default.
	HeartbeatMs int64

	// Logger is the producer-side diagnostic logger. task.ForApp(ctx)
	// pre-contextualises it with run_id / app_id / instance_id; the
	// handle adds task_id internally. nil ⇒ handle uses a no-op logger
	// (zero-value zerolog.Logger writes nowhere). Pointer because
	// zerolog.Logger contains a []byte and cannot be compared with ==.
	Logger *zerolog.Logger
}

type TaskApiI interface {
	// Spawn creates a new task. callerCtx is composed with the host's
	// mount-cancel channel so the returned handle's ctx cancels on
	// either signal (or on terminal Done/Error). Pass
	// context.Background() to opt out of caller-side scoping.
	Spawn(callerCtx context.Context, opts SpawnOpts) (h HandleI, err error)

	// WatchAll attaches an observer to task.> on the host bus.
	// Identical to task.WatchAll(bus, obs) — exposed here so apps
	// don't need to thread the bus.
	WatchAll(obs ObserverI) (unsubscribe func(), err error)

	// RequestCancel publishes a cancel for the given task id.
	RequestCancel(id TaskIdT, reason string) (err error)

	// ListInflight queries the M3 supervisor's snapshot via the
	// SubjectListInflight request/reply. Times out at ListTimeoutMs
	// from ApiConfig. Returns an empty slice (not an error) when no
	// supervisor is running and the bus' request timeout fires —
	// callers distinguish "no supervisor" from "no in-flight tasks"
	// by the err: a nil err with empty entries means the supervisor
	// returned an empty snapshot; an error means the supervisor was
	// unreachable.
	ListInflight() (entries []InflightSnapshotEntry, err error)

	// AppId returns the owner identity the API will stamp on spawned
	// tasks. Useful for diagnostic logging at the app boundary.
	AppId() (id app.AppIdT)

	// InstanceKey returns the host-minted per-window instance id. Zero
	// when the API was constructed without one (tests, standalone CLI).
	InstanceKey() (key uint64)

	// RunId returns the process-wide run id. Empty when the API was
	// constructed without one.
	RunId() (id string)
}

type TaskIdT string

type UnitE uint8