pauseresume

type Coordinator interface {
	// Request records a pause and returns its opaque Token. When a
	// checkpoint store is configured the pause record (including the
	// optional trajectory) is persisted; a non-serialisable trajectory
	// fails loud with trajectory.ErrUnserializable and nothing is
	// persisted.
	Request(ctx context.Context, req PauseRequest) (Pause, error)

	// Resume terminates a pause: it validates the resuming identity
	// scope, re-attaches any tool-context handles via the
	// HandleRegistry (propagating trajectory.ErrToolContextLost on a
	// lost handle), marks the record resumed, and clears the
	// checkpoint. A second Resume of the same Token returns
	// ErrAlreadyResumed.
	//
	// `decision` is the typed marker carried on the emitted
	// `pause.resumed` event so wire consumers (the Console, third-party
	// clients, integration tests) can distinguish approve from reject
	// from generic resume from timeout without parsing free-form
	// `Reason` strings. An invalid Decision is rejected loud with
	// ErrInvalidDecision — there is no untyped default (§13 fail-loudly,
	// D-096).
	Resume(ctx context.Context, token Token, decision Decision, payload map[string]any) error

	// Status returns a read-only snapshot of a pause record's
	// lifecycle. When the Token is absent from the in-memory registry
	// but a checkpoint store is configured, Status falls back to a
	// checkpoint load (the restart-survival path). An unknown Token
	// returns ErrPauseNotFound.
	Status(ctx context.Context, token Token) (Status, error)

	// List returns a paginated snapshot of pause records visible under
	// the caller's identity scope (Phase 72e — the `pause.list`
	// Protocol surface). Read-only: it does NOT mutate the registry,
	// does NOT call Resume, and does NOT clear checkpoints.
	//
	// Identity-mandatory: a missing (tenant, user, session) triple on
	// req.Identity returns wrapped ErrIdentityRequired. Pagination is
	// mandatory — a 0 / negative / over-max PageSize, or a negative
	// Page, returns wrapped ErrInvalidPage; the snapshot is never
	// silently clamped.
	//
	// Cross-tenant visibility: when req.Filter.TenantIDs names a tenant
	// other than req.Identity.TenantID (or more than one tenant), the
	// caller MUST set req.AdminScoped — otherwise List returns wrapped
	// ErrCrossTenantScope. The Coordinator does NOT read the scope from
	// ctx; the Protocol-edge handler is responsible for verifying the
	// `auth.ScopeAdmin` claim and setting AdminScoped (separation of
	// concerns — D-079).
	List(ctx context.Context, req ListRequest) (ListResponse, error)
}

type Decision string

type ListFilter struct {
	// States narrows by lifecycle state. Empty defaults to
	// [StatusPaused] — the intervention-queue use case.
	States []State
	// TenantIDs narrows to a tenant set. Empty defaults to the
	// caller's own tenant. A foreign tenant OR len>1 requires
	// ListRequest.AdminScoped.
	TenantIDs []string
	// UserIDs narrows to a user set within the visible tenants.
	UserIDs []string
	// SessionIDs narrows to a session set.
	SessionIDs []string
	// RunIDs narrows to a run set.
	RunIDs []string
	// Reasons narrows to one or more canonical pause reasons.
	Reasons []Reason
	// Since is an optional lower bound on PausedAt (inclusive).
	Since time.Time
	// Until is an optional upper bound on PausedAt (inclusive).
	Until time.Time
}

type ListRequest struct {
	// Identity is the caller's (tenant, user, session) triple.
	// Mandatory — an incomplete triple fails closed with
	// ErrIdentityRequired.
	Identity identity.Identity
	// Filter narrows the snapshot. An empty filter means "the caller's
	// own identity scope, status=paused".
	Filter ListFilter
	// Page is the 1-based page number. 0 is treated as 1; a negative
	// Page fails closed with ErrInvalidPage.
	Page int
	// PageSize is the per-page row count. 0 is treated as the default
	// (DefaultListPageSize); a negative or over-max value fails closed
	// with ErrInvalidPage.
	PageSize int
	// AdminScoped is true when the caller carries the verified
	// auth.ScopeAdmin claim. Set by the Protocol-edge handler; the
	// Coordinator itself does NOT read the scope from ctx.
	AdminScoped bool
}

type ListResponse struct {
	// Snapshots is the page of pause records, ordered PausedAt
	// descending (newest first).
	Snapshots []Pause
	// Statuses is parallel to Snapshots — Statuses[i] is the lifecycle
	// status of Snapshots[i].
	Statuses []Status
	// Page is the 1-based page number this response covers.
	Page int
	// PageSize is the per-page row count applied.
	PageSize int
	// PageCount is the total number of pages over the filtered set.
	PageCount int
	// TotalRows is the total filtered row count across all pages.
	TotalRows int
	// Truncated is true when a status=resumed filter was requested but
	// the resumed slice has aged out of the in-memory registry — see
	// the Coordinator's destructive-on-resume contract (coordinator.go).
	Truncated bool
}

type Option func(*coordinator)

type Pause struct {
	// Token is the opaque runtime-issued handle for this pause.
	Token Token
	// Reason is one of the four canonical pause reasons.
	Reason Reason
	// Payload is the sanitised, bounded pause payload (auth URL +
	// scopes for OAuth, approval context for HITL, etc.).
	Payload map[string]any
	// PausedAt is the wall-clock time the pause was recorded.
	PausedAt time.Time
	// Identity is the (tenant, user, session) triple the pause was
	// recorded under. Resume validates the resuming scope against it.
	Identity identity.Identity
}

type PausePayloadArtifactRoutedPayload struct {
	events.SafeSealed
	// Token is the opaque pause Token whose Payload was routed.
	Token string
	// ArtifactID is the content-addressed ID of the artifact the
	// heavy Payload was materialised into.
	ArtifactID string
	// PayloadBytes is the serialised byte length of the routed Payload.
	PayloadBytes int
	// ThresholdBytes is the configured heavy-content threshold the
	// PayloadBytes met or exceeded.
	ThresholdBytes int
}

type PauseRequest struct {
	// Identity is the (tenant, user, session) triple the paused run
	// belongs to. Mandatory — a partial triple fails closed with
	// ErrIdentityRequired (CLAUDE.md §6 rule 9).
	Identity identity.Identity
	// Reason is one of the four canonical pause reasons. An invalid
	// reason fails closed with ErrInvalidReason.
	Reason Reason
	// Payload is the sanitised, bounded pause payload. Optional;
	// may be nil.
	Payload map[string]any
	// Trajectory, when non-nil, is checkpointed alongside the pause
	// record when a checkpoint store is configured. A non-serialisable
	// trajectory fails Request loud with trajectory.ErrUnserializable
	// — the pause is NOT half-persisted. Optional; may be nil (a pause
	// with no trajectory is valid — e.g. a pre-run approval gate).
	Trajectory *trajectory.Trajectory
}

type PauseRequestedPayload struct {
	events.SafeSealed
	// Token is the opaque pause Token.
	Token string
	// Reason is the canonical pause reason string.
	Reason string
}

type PauseResumedPayload struct {
	events.SafeSealed
	// Token is the opaque pause Token.
	Token string
	// Reason is the canonical pause reason string (one of the four
	// canonical pause reasons — the reason the pause was *requested*).
	Reason string
	// Decision is the typed marker indicating *how* the pause resumed
	// (approve / reject / resume / timeout). Wire consumers switch on
	// this value rather than parsing `Reason` strings. See D-096.
	Decision Decision
}

type Reason = planner.PauseReason

type State string

type Status struct {
	// State is StatusPaused or StatusResumed.
	State State
	// Reason is the pause reason recorded at Request time.
	Reason Reason
	// PausedAt is the wall-clock time the pause was recorded.
	PausedAt time.Time
	// ResumedAt is the wall-clock time Resume was called; the zero
	// value unless State == StatusResumed.
	ResumedAt time.Time
	// Decision is the typed marker the pause was resumed with
	// (approve / reject / resume / timeout — D-096); the zero value
	// while State == StatusPaused. Lets an in-process observer (the
	// steering RunLoop's timeout detection — Phase 111c / D-200)
	// distinguish a sweeper-reaped timeout from a legitimate resume
	// without parsing event payloads. Process-local: a rehydrated
	// (restart-survival) Status never carries a Decision because a
	// resumed checkpoint is deleted, not kept.
	Decision Decision
}

type SweeperOption func(*sweeperConfig)

type Token string