odidere/internal/db/models.go

package db

import (
	"encoding/json/jsontext"
	"time"
)

// ExecutionStatus is the state of one tool call, as stored in the executions
// table (one row for every tool call in an assistant message).
//
// The row tracks the call's lifecycle; it does not store the call's
// outcome. The outcome lives in a tool result message row in the messages
// table, matched to the call by tool_call_id.
//
// Lifecycle, by tool kind:
//
// A. Approval not required:
//
//	┌────────────┐    ┌────────────┐
//	│  running   ├┄┄┄▶│ completed  │
//	└────────────┘    └────────────┘
//
// B. Approval required:
//
//	┌────────────┐    ┌────────────┐    ┌────────────┐    ┌────────────┐
//	│  pending   ├───▶│  approved  ├───▶│  running   ├┄┄┄▶│ completed  │
//	└────────────┘    └────────────┘    └────────────┘    └────────────┘
//	      │
//	      ▼
//	┌────────────┐
//	│   denied   │
//	└────────────┘
//
// The dashed arrow from running to completed indicates the possibility that a
// tool call may not complete. if a tool call is interrupted, the row ends at
// running. See [ExecutionStatusRunning].
type ExecutionStatus string

const (
	// ExecutionStatusApproved: tool call approved by user.
	// The call has not launched yet.
	ExecutionStatusApproved ExecutionStatus = "approved"
	// ExecutionStatusCompleted: the tool call returned output or an error.
	// Terminal.
	ExecutionStatusCompleted ExecutionStatus = "completed"
	// ExecutionStatusDenied: user refused the tool call. Terminal.
	ExecutionStatusDenied ExecutionStatus = "denied"
	// ExecutionStatusPending: the call awaits a user decision.
	ExecutionStatusPending ExecutionStatus = "pending"
	// ExecutionStatusRunning: the tool call either:
	// A. is about to be started,
	// B. was started and is still executing,
	// C. was interrupted before it started or finished (terminal).
	ExecutionStatusRunning ExecutionStatus = "running"
)

// Execution represents a row in the executions table: one tool call
// within an assistant message and its current state.
type Execution struct {
	CreatedAt  time.Time       `json:"created_at"`
	Id         string          `json:"id"`
	MessageId  string          `json:"message_id"`
	Status     ExecutionStatus `json:"status"`
	ToolCallId string          `json:"tool_call_id"`
	UpdatedAt  time.Time       `json:"updated_at"`
}

// Conversation represents a stored conversation.
type Conversation struct {
	CreatedAt time.Time `json:"created_at"`
	Id        string    `json:"id"`
	Title     *string   `json:"title"`
	UpdatedAt time.Time `json:"updated_at"`
	UserId    string    `json:"user_id"`
}

// MessageRole defines the permitted roles for messages.
type MessageRole string

const (
	MessageRoleSystem    MessageRole = "system"
	MessageRoleDeveloper MessageRole = "developer"
	MessageRoleUser      MessageRole = "user"
	MessageRoleAssistant MessageRole = "assistant"
	MessageRoleTool      MessageRole = "tool"
)

// Message represents a stored chat message. Content holds the
// wire-format JSON for the message — the exact JSON object that
// appears in the OpenAI Chat Completions messages array.
type Message struct {
	// Content is the model-visible message JSON, without inference
	// metadata.
	Content string `json:"content"`
	// ConversationId identifies the conversation that owns this message
	// row.
	ConversationId string `json:"conversation_id"`
	// CreatedAt is the database timestamp when this message row was
	// created, not the provider's completion creation time.
	CreatedAt time.Time `json:"created_at"`
	// Id identifies this database message row, not a completion or request.
	Id string `json:"id"`
	// Metadata holds inference JSON decoded from the stored JSONB value.
	// Nil means no metadata was saved; content edits preserve metadata.
	Metadata jsontext.Value `json:"metadata"`
	// Role is the message role stored separately for row queries.
	Role MessageRole `json:"role"`
	// Sequence is this row's ordering position within its conversation.
	Sequence int `json:"sequence"`
	// UpdatedAt is the database timestamp of this message row's last
	// update.
	UpdatedAt time.Time `json:"updated_at"`
}

// Session represents a user login session.
type Session struct {
	CreatedAt     time.Time  `json:"created_at"`
	DeactivatedAt *time.Time `json:"deactivated_at"`
	Id            string     `json:"id"`
	UpdatedAt     time.Time  `json:"updated_at"`
	UserId        string     `json:"user_id"`
}

// UserRole defines the permitted roles for users.
type UserRole string

const (
	UserRoleOwner UserRole = "owner"
)

// User represents a stored user account.
type User struct {
	CreatedAt     time.Time  `json:"created_at"`
	DeactivatedAt *time.Time `json:"deactivated_at"`
	Id            string     `json:"id"`
	Name          string     `json:"name"`
	Password      string     `json:"password"`
	Role          UserRole   `json:"role"`
	UpdatedAt     time.Time  `json:"updated_at"`
}