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"`
}

type AutomatonRole string

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

type ContextKind string

type EventType string

type PastureRole string

type PhaseId string

type Pipeline []PhaseId

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 TaskTracker interface {
	// ─── Embedded: Provenance task CRUD, edges, labels, comments,
	// agents (Human/ML/Software), activities. See provenance.Tracker. ───
	provenance.Tracker

	// RecordEvent persists a single audit event. Returns an error if the
	// underlying store is unavailable or the write fails. The caller
	// (typically a Temporal activity) 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
}