session

type Author struct {
	UserID      types.UserID `firestore:"user_id" json:"user_id"`
	DisplayName string       `firestore:"display_name" json:"display_name"`
	// SlackUserID is set when the author is a Slack workspace member.
	SlackUserID *string `firestore:"slack_user_id,omitempty" json:"slack_user_id,omitempty"`
	Email       *string `firestore:"email,omitempty" json:"email,omitempty"`
}

type ChannelRef struct {
	SlackThread *slack.Thread `firestore:"slack_thread,omitempty" json:"slack_thread,omitempty"`
}

type Message struct {
	ID        types.MessageID `firestore:"id" json:"id"`
	SessionID types.SessionID `firestore:"session_id" json:"session_id"`
	Type      MessageType     `firestore:"type" json:"type"`       // Type only affects Slack display method
	Content   string          `firestore:"content" json:"content"` // All stored as plain text
	CreatedAt time.Time       `firestore:"created_at" json:"created_at"`
	UpdatedAt time.Time       `firestore:"updated_at" json:"updated_at"`

	// TicketID denormalizes Session.TicketID onto each Message so Ticket-
	// level timeline queries do not require a per-Message Session join.
	// nil when the owning Session is ticketless.
	TicketID *types.TicketID `firestore:"ticket_id,omitempty" json:"ticket_id,omitempty"`

	// TurnID identifies which Turn (req/res cycle) produced this Message.
	// nil when the Message is not tied to an AI work unit (e.g. Slack
	// thread messages that were not @warren mentions).
	TurnID *types.TurnID `firestore:"turn_id,omitempty" json:"turn_id,omitempty"`

	// Author is required for Type=user and nil otherwise.
	Author *Author `firestore:"author,omitempty" json:"author,omitempty"`

	// Revisions carries the historical content of an updatable Message.
	// The current Content field is always the latest revision; Revisions
	// is the chronologically-ordered list of prior values (oldest first).
	// Empty for messages that have never been updated in-place.
	//
	// Updatable messages are used by Web/CLI Sessions so that live task
	// progress and HITL prompts can replace the current display row
	// while preserving the full trace for later review. Slack Sessions
	// keep their own update history in the Slack thread and do not
	// populate this field.
	Revisions []MessageRevision `firestore:"revisions,omitempty" json:"revisions,omitempty"`
}

type MessageRevision struct {
	Content   string    `firestore:"content" json:"content"`
	CreatedAt time.Time `firestore:"created_at" json:"created_at"`
}

type MessageType string

type Session struct {
	ID        types.SessionID     `firestore:"id" json:"id"`
	TicketID  types.TicketID      `firestore:"ticket_id" json:"ticket_id"`
	RequestID string              `firestore:"request_id" json:"request_id"`
	Status    types.SessionStatus `firestore:"status" json:"status"`
	UserID    types.UserID        `firestore:"user_id" json:"user_id"`
	Query     string              `firestore:"query" json:"query"`
	SlackURL  string              `firestore:"slack_url" json:"slack_url"`
	Intent    string              `firestore:"intent" json:"intent"`
	CreatedAt time.Time           `firestore:"created_at" json:"created_at"`
	UpdatedAt time.Time           `firestore:"updated_at" json:"updated_at"`

	// Source identifies the channel the Session is bound to. Empty on data
	// written by pre-redesign code; readers should treat the empty value as
	// "unknown" and rely on migration to backfill.
	Source SessionSource `firestore:"source,omitempty" json:"source,omitempty"`

	// ChannelRef carries the external channel identifier for Slack
	// Sessions. nil for Web/CLI.
	ChannelRef *ChannelRef `firestore:"channel_ref,omitempty" json:"channel_ref,omitempty"`

	// TicketIDPtr allows nil (ticketless Slack Session). While the
	// non-nullable TicketID above remains for legacy writers, new code
	// should prefer reading/writing through TicketIDPtr. Phase 7 merges
	// these two into a single nullable field.
	TicketIDPtr *types.TicketID `firestore:"ticket_id_ptr,omitempty" json:"ticket_id_ptr,omitempty"`

	// Lock expresses the Slack Session's activity lock (nil = unlocked).
	// Always nil on Web and CLI Sessions, since those are born per-request.
	Lock *SessionLock `firestore:"lock,omitempty" json:"lock,omitempty"`

	// LastActiveAt records the moment the most recent Turn completed. Pure
	// informational; lock eligibility is judged from Lock.ExpiresAt, not
	// from this field.
	LastActiveAt time.Time `firestore:"last_active_at,omitzero" json:"last_active_at,omitzero"`
}

type SessionLock struct {
	// HolderID is the request_id of the goroutine holding the lock.
	HolderID string `firestore:"holder_id" json:"holder_id"`
	// AcquiredAt is the instant the lock was first granted.
	AcquiredAt time.Time `firestore:"acquired_at" json:"acquired_at"`
	// ExpiresAt is AcquiredAt + TTL (default 3 minutes). The lock is
	// considered stale once ExpiresAt <= now, at which point another
	// holder may take over.
	ExpiresAt time.Time `firestore:"expires_at" json:"expires_at"`
}

type SessionSource string

type Turn struct {
	ID        types.TurnID    `firestore:"id" json:"id"`
	SessionID types.SessionID `firestore:"session_id" json:"session_id"`
	RequestID string          `firestore:"request_id" json:"request_id"`
	Status    TurnStatus      `firestore:"status" json:"status"`
	Intent    string          `firestore:"intent" json:"intent"`
	StartedAt time.Time       `firestore:"started_at" json:"started_at"`
	EndedAt   *time.Time      `firestore:"ended_at,omitempty" json:"ended_at,omitempty"`
}

type TurnStatus string