protocol

type AuditEvent struct {
	EpochId   string         `json:"epochId"`
	Phase     PhaseId        `json:"phase"`
	Role      string         `json:"role"`
	EventType EventType      `json:"eventType"`
	Payload   map[string]any `json:"payload"`
	Timestamp time.Time      `json:"timestamp"`
	DedupKey  string         `json:"dedupKey,omitempty"`
}

type AutomatonRole string

type Context struct {
	Kind      ContextKind `json:"kind"`
	ContextId string      `json:"contextId"`
}

type ContextKind string

type EpochState struct {
	EpochId           string                  `json:"epochId"`
	CurrentPhase      PhaseId                 `json:"currentPhase"`
	CurrentRole       RoleId                  `json:"currentRole"`
	CompletedPhases   []PhaseId               `json:"completedPhases"`
	ReviewVotes       map[ReviewAxis]VoteType `json:"reviewVotes"`
	BlockerCount      int                     `json:"blockerCount"`
	TransitionHistory []TransitionRecord      `json:"transitionHistory"`
	// ReviewCycles tracks per-slice review-fix cycle history.
	// Key: slice task ID. Value: ordered list of review rounds for that slice.
	ReviewCycles       map[string][]ReviewCycleRecord `json:"reviewCycles,omitempty"`
	LastError          *string                        `json:"lastError,omitempty"`
	ActiveSessionCount int                            `json:"activeSessionCount"`
	// ActiveSessions holds the sessions registered with this epoch, in
	// registration order, de-duplicated by SessionId. ActiveSessionCount stays
	// equal to len(ActiveSessions); both are maintained together. omitempty so
	// epochs driven without the signal-driven control loop serialize unchanged.
	ActiveSessions []RegisterSessionSignal `json:"activeSessions,omitempty"`
	// SliceProgress holds the slice-progress events reported to this epoch, in
	// arrival order. omitempty for backward-compatible serialization.
	SliceProgress []SliceProgressSignal `json:"sliceProgress,omitempty"`
}

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

type EventType string

type PastureRole string

type PhaseAdvanceSignal struct {
	ToPhase      PhaseId `json:"toPhase"`
	TriggeredBy  string  `json:"triggeredBy"`
	ConditionMet string  `json:"conditionMet"`
}

type PhaseId string

type PhaseSpec struct {
	// Transitions lists all target PhaseIds reachable from this phase.
	Transitions []PhaseId
}

type Pipeline []PhaseId

type QueryName string

type QueryStateResult struct {
	CurrentPhase         PhaseId                 `json:"currentPhase"`
	CurrentRole          RoleId                  `json:"currentRole"`
	TransitionHistory    []TransitionRecord      `json:"transitionHistory"`
	Votes                map[ReviewAxis]VoteType `json:"votes"`
	LastError            *string                 `json:"lastError,omitempty"`
	AvailableTransitions []PhaseId               `json:"availableTransitions"`
	ActiveSessionCount   int                     `json:"activeSessionCount"`
}

type RegisterSessionSignal struct {
	EpochId      string `json:"epochId"`
	SessionId    string `json:"sessionId"`
	Role         string `json:"role"`
	ModelHarness string `json:"modelHarness"`
	Model        string `json:"model"`
}

type ReviewAxis string

type ReviewCycleRecord struct {
	// SliceId is the task ID of the slice being reviewed.
	SliceId string `json:"sliceId"`
	// Round is the 1-based review cycle number for this slice (max 3).
	Round int `json:"round"`
	// Votes maps each reviewer axis to its vote for this round.
	Votes map[ReviewAxis]VoteType `json:"votes"`
	// FindingCounts maps severity level to the number of findings.
	FindingCounts map[SeverityLevel]int `json:"findingCounts"`
	// Timestamp records when the review round completed.
	Timestamp time.Time `json:"timestamp"`
}

type ReviewVoteSignal struct {
	Axis       ReviewAxis `json:"axis"`
	Vote       VoteType   `json:"vote"`
	ReviewerId string     `json:"reviewerId"`
}

type RoleId string

type SessionEntry struct {
	SessionId      string  `json:"sessionId"`
	EntryIndex     int     `json:"entryIndex"`
	Provider       string  `json:"provider"`
	EntryType      string  `json:"entryType"`
	Role           string  `json:"role"`
	TimestampMs    *int64  `json:"timestampMs,omitempty"`
	ContentPreview *string `json:"contentPreview,omitempty"` // max 500 chars
	TokensIn       *int    `json:"tokensIn,omitempty"`
	TokensOut      *int    `json:"tokensOut,omitempty"`
	HasToolUse     bool    `json:"hasToolUse"`
	ToolKind       *string `json:"toolKind,omitempty"`     // ACP-aligned tool classification
	ToolNamesCsv   *string `json:"toolNamesCsv,omitempty"` // comma-separated tool names
	HasThinking    bool    `json:"hasThinking"`
	IsError        bool    `json:"isError"`
	StopReason     *string `json:"stopReason,omitempty"`    // ACP per-turn stop reason
	RawByteLength  *int    `json:"rawByteLength,omitempty"` // raw JSON byte count
	ToolCallId     *string `json:"toolCallId,omitempty"`    // MCP correlation
	EntryId        *string `json:"entryId,omitempty"`       // provider-native ID
	ParentEntryId  *string `json:"parentEntryId,omitempty"` // parent entry link
	Depth          int     `json:"depth"`                   // 0 = message, 1 = content part
	ParentIndex    *int    `json:"parentIndex,omitempty"`   // entryIndex of parent (nil for depth=0)
	ToolInput      *string `json:"toolInput,omitempty"`     // tool_use input JSON
	ToolOutput     *string `json:"toolOutput,omitempty"`    // tool_result output JSON
	Extra          *string `json:"extra,omitempty"`         // JSON overflow for provider-specific data
}

type SeverityLevel string

type SignalTopic string

type SliceCompleteSignal struct {
	Success bool    `json:"success"`
	Output  string  `json:"output,omitempty"`
	Error   *string `json:"error,omitempty"`
}

type SliceExecutionMode string

type SliceProgressSignal struct {
	SliceId    string `json:"sliceId"`
	LeafTaskId string `json:"leafTaskId"`
	StageName  string `json:"stageName"`
	Completed  bool   `json:"completed"`
}

type SliceStartSignal struct {
	Mode           SliceExecutionMode `json:"mode"`
	Command        string             `json:"command,omitempty"`
	TimeoutSeconds int                `json:"timeoutSeconds,omitempty"`
}

type TaskAssignmentState struct {
	TaskID       provenance.TaskID
	Slot         provenance.AssignmentSlotID
	AssignmentID provenance.AssignmentID
	Occupant     provenance.ActorID
}

type TaskAssignmentTransferError struct {
	Kind TaskAssignmentTransferErrorKind
	// contains filtered or unexported fields
}

type TaskAssignmentTransferErrorKind uint8

type TaskTracker interface {
	// ─── Embedded: Provenance task reads, edges/labels/comments reads,
	// agents (Human/ML/Software), activities, plus the journaled mutation
	// binder As(actor, authority) and the global journal surface Journal().
	// See provenance.Tracker. ───
	provenance.Tracker

	// Create mints a new task and journals its birth (status open).
	Create(namespace, title, description string, taskType provenance.TaskType, priority provenance.Priority, phase provenance.Phase) (provenance.Task, error)

	// Update applies partial metadata (Title/Description/Priority/Phase/Notes)
	// to a task as one journaled operation. Status is NOT a metadata field:
	// use the lifecycle verbs Start/Stop/Reopen/CloseTask to change status.
	Update(id provenance.TaskID, fields provenance.UpdateFields) (provenance.Task, error)

	// CloseTask transitions {open,in_progress} → closed, materialising reason.
	CloseTask(id provenance.TaskID, reason string) (provenance.Task, error)

	// Start transitions open → in_progress through the journaled lifecycle FSM.
	Start(id provenance.TaskID) (provenance.Task, error)

	// Stop transitions in_progress → open through the journaled lifecycle FSM.
	Stop(id provenance.TaskID) (provenance.Task, error)

	// Reopen transitions closed → open through the journaled lifecycle FSM.
	Reopen(id provenance.TaskID) (provenance.Task, error)

	// AddEdge journals a typed edge from sourceId to targetId.
	AddEdge(sourceId provenance.TaskID, targetId string, kind provenance.EdgeKind) error

	// RemoveEdge journals the removal of the edge from sourceId to targetId.
	RemoveEdge(sourceId provenance.TaskID, targetId string, kind provenance.EdgeKind) error

	// AddLabel journals attaching a label to a task.
	AddLabel(id provenance.TaskID, label string) error

	// RemoveLabel journals detaching a label from a task.
	RemoveLabel(id provenance.TaskID, label string) error

	// AddComment journals a comment on a task authored by authorId.
	AddComment(id provenance.TaskID, authorId provenance.AgentID, body string) (provenance.Comment, error)

	// TransferTaskAssignment atomically transfers the active assignment in one
	// supported task slot to its requested successor. The caller supplies only
	// semantic task and actor values; Pasture resolves the current assignment
	// internally and returns semantic prior and successor states.
	TransferTaskAssignment(ctx context.Context, request TransferTaskAssignmentRequest) (TransferTaskAssignmentResult, error)

	// RecordEvent persists a single audit event. Returns an error if the
	// underlying store is unavailable or the write fails. The caller
	// (typically a durable workflow step) is responsible for retry policy.
	//
	// PROPOSAL-2 §7.11: workflows call this then immediately call
	// AttachContext with ContextEpoch. Free-floating events use other
	// ContextKind values (Git/Skill/Session).
	//
	// Note: callers that need the inserted event_id (so they can attach
	// context_edges rows in the same logical step) should prefer
	// RecordEventReturningId — it bundles the write + id-recovery in a
	// single call, removing the post-write SELECT MAX(id) round-trip the
	// S9 free-floating helpers had to do as a workaround.
	RecordEvent(ctx context.Context, event AuditEvent) error

	// RecordEventReturningId persists a single audit event and returns the
	// audit_events.id of the just-inserted row. The implementation reads the
	// id from sql.Result.LastInsertId on the SAME INSERT statement that wrote
	// the row, so the returned id is race-safe under any level of write
	// contention — independent of the D11 "low write contention" deployment
	// binding. Returns the new id and a nil error on success; on failure
	// returns 0 and an actionable *pasterrors.StructuredError.
	//
	// This is the canonical RecordEvent entry point for workflow activities
	// (PROPOSAL-2 §7.11): RecordTransition and RecordAuditEvent call this
	// then immediately call AttachContext(eventId, ContextEpoch, epochId)
	// to record the event-to-epoch correlation. Free-floating helpers
	// (RecordGitEvent / RecordSkillEvent / RecordSessionEvent) also use it
	// in place of the older SELECT MAX(id) workaround that this method
	// supersedes (Phase 11 R1-B per finding aura-plugins-d1h6y).
	//
	// Behaviour for non-SQLite trail backends (e.g. *audit.InMemoryAuditTrail
	// used in tests): the returned id is a synthetic per-trail monotonic
	// counter — it is NOT a real audit_events row id and MUST NOT be
	// persisted across processes. The counter is incremented atomically per
	// call so concurrent test goroutines always observe distinct ids,
	// matching the SQLite trail's per-statement-LastInsertId guarantee.
	// AttachContext on an in-memory trail is a no-op anyway (no
	// context_edges table backing it), so the synthetic id is only
	// meaningful for AttachContext-relative assertions in unit tests that
	// exercise the workflow integration path without paying for a real
	// SQLite file.
	RecordEventReturningId(ctx context.Context, event AuditEvent) (int64, error)

	// QueryEvents returns audit events filtered by epoch and (optionally)
	// phase / role. Results are returned in chronological order. epochId
	// is required and is always part of the WHERE clause.
	//
	// Note: this is the legacy v1 query path; new callers should prefer
	// Timeline(ctx, ContextEpoch, epochId) which uses the context_edges
	// JOIN and works for all ContextKind values, not just epoch.
	QueryEvents(ctx context.Context, epochId string, phase *PhaseId, role *string) ([]AuditEvent, error)

	// RecordSessionEntries persists a batch of SessionEntry records
	// atomically (single transaction). Nil or empty slices are no-ops.
	RecordSessionEntries(ctx context.Context, entries []SessionEntry) error

	// QuerySessionEntries returns all session entries for sessionId in
	// insertion order. Returns an empty (non-nil) slice when no entries
	// exist for sessionId.
	QuerySessionEntries(ctx context.Context, sessionId string) ([]SessionEntry, error)

	// SetAgentCategories upserts the (automaton, pasture-role) pair for
	// the given agent into pasture_agent_categories. Idempotent: a second
	// call with the same id replaces the row. Both AutomatonRole and
	// PastureRole MUST be valid enum values (see IsValid); a nil/zero
	// value is permitted and stored as the literal "None".
	//
	// Returns *pasterrors.StructuredError{Category: CategoryStorage} on
	// write failure, or {Category: CategoryValidation} if either enum
	// value is unknown.
	SetAgentCategories(id provenance.AgentID, automaton AutomatonRole, pastureRole PastureRole) error

	// AgentCategories returns the (automaton, pasture-role) pair stored
	// for id. Returns ("None", "None", nil) if no row exists for id.
	AgentCategories(id provenance.AgentID) (AutomatonRole, PastureRole, error)

	// AttachContext adds a row to context_edges binding eventId to the
	// (kind, contextId) pair. The (event_id, context_kind, context_id)
	// triple is the BCNF composite primary key — duplicate inserts are
	// idempotent (returns nil; the existing row is preserved).
	//
	// kind MUST be a valid ContextKind (kind.IsValid()); contextId MUST
	// be non-empty. Validation failures return CategoryValidation.
	AttachContext(ctx context.Context, eventId int64, kind ContextKind, contextId string) error

	// EventContexts returns the typed contexts attached to eventId, in
	// insertion order. Returns an empty (non-nil) slice when no edges
	// exist for eventId.
	EventContexts(ctx context.Context, eventId int64) ([]Context, error)

	// Timeline returns all events whose context_edges row matches the
	// (kind, contextId) pair, in chronological order. The intended usage:
	//
	//   events := tracker.Timeline(ctx, ContextEpoch, epochId)
	//   events := tracker.Timeline(ctx, ContextGit, "<sha>")
	//
	// A nil/empty contextId returns an empty slice (no error).
	Timeline(ctx context.Context, kind ContextKind, contextId string) ([]AuditEvent, error)

	// Close releases all resources held by the tracker. It is safe to call
	// Close multiple times; the second and subsequent calls return nil.
	//
	// Note: provenance.Tracker also declares Close(), and the embedded
	// method satisfies this interface requirement; implementations MUST
	// however ensure both subsystems (the provenance.Tracker AND the
	// underlying audit.Trail's *sql.DB) are closed exactly once.
	Close() error
}

type TransferTaskAssignmentRequest struct {
	TaskID           provenance.TaskID
	Slot             provenance.AssignmentSlotID
	NextAssignmentID provenance.AssignmentID
	ActorID          provenance.ActorID
	NextOccupant     provenance.ActorID
}

type TransferTaskAssignmentResult struct {
	Previous TaskAssignmentState
	Next     TaskAssignmentState
	Replayed bool
}

type TransitionError struct {
	Violations []string
}

type TransitionRecord struct {
	FromPhase    PhaseId   `json:"fromPhase"`
	ToPhase      PhaseId   `json:"toPhase"`
	Timestamp    time.Time `json:"timestamp"`
	TriggeredBy  string    `json:"triggeredBy"`
	ConditionMet string    `json:"conditionMet"`
	Success      bool      `json:"success"`
}

type VoteType string