domain

package
v0.0.24 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 15, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package domain contains the core domain model structs for Substrate.

Index

Constants

View Source 
const TimeFormat = "2006-01-02T15:04:05.000Z"

TimeFormat is the ISO 8601 format used for all DB-stored timestamps.

Variables

This section is empty.

Functions

func ComposePlanDocument 

func ComposePlanDocument(plan Plan, subPlans []TaskPlan) string

ComposePlanDocument reconstructs the full reviewable plan document from the persisted orchestration plan and repo sub-plans.

func ComposeSubPlansContent 

func ComposeSubPlansContent(subPlans []TaskPlan) string

ComposeSubPlansContent assembles all sub-plan contents into a single comment-ready string. A single sub-plan is returned as-is (trimmed). Multiple sub-plans are each prefixed with a "## SubPlan: {repo}" heading and separated by a blank line.

func FormatIncompleteSubPlanIssue 

func FormatIncompleteSubPlanIssue(repoName, detail string) string

FormatIncompleteSubPlanIssue standardizes parser feedback for insufficiently detailed sub-plans.

func FormatTime 

func FormatTime(t time.Time) string

FormatTime formats a time.Time for DB storage.

func NewID 

func NewID() string

NewID generates a new ULID string.

func Now 

func Now() time.Time

Now returns the current time in UTC.

func ParseTime 

func ParseTime(s string) (time.Time, error)

ParseTime parses a DB-stored timestamp string.

Types

type Critique 

type Critique struct {
	ID            string
	ReviewCycleID string
	FilePath      string
	LineNumber    *int
	Description   string
	Suggestion    string // optional improvement suggestion from review agent
	Severity      CritiqueSeverity
	Status        CritiqueStatus
	CreatedAt     time.Time
}

Critique is a single review finding within a review cycle.

type CritiqueSeverity 

type CritiqueSeverity string

CritiqueSeverity represents the severity of a critique. 

const (
	CritiqueCritical CritiqueSeverity = "critical"
	CritiqueMajor    CritiqueSeverity = "major"
	CritiqueMinor    CritiqueSeverity = "minor"
	CritiqueNit      CritiqueSeverity = "nit"
)

type CritiqueStatus 

type CritiqueStatus string

CritiqueStatus represents whether a critique is open or resolved. 

const (
	CritiqueOpen     CritiqueStatus = "open"
	CritiqueResolved CritiqueStatus = "resolved"
)

type EventType 

type EventType string

EventType is a string type for event type constants. 

const (
	// WorktreeCreating is a pre-hook event emitted before git-work checkout.
	// Adapters can abort by returning an error.
	EventWorktreeCreating EventType = "worktree.creating"

	// WorktreeCreated is a post-hook event emitted after git-work checkout succeeds.
	EventWorktreeCreated EventType = "worktree.created"

	// WorktreeReused is a post-hook event emitted when an existing worktree is reused
	// during differential re-implementation.
	EventWorktreeReused EventType = "worktree.reused"
)

Event type constants for system events. These are used for routing and persistence.

Pre-hook events run hooks BEFORE persistence. If any hook rejects, the event is not persisted and the operation should be aborted. 

const (
	// Work item lifecycle events
	EventWorkItemIngested     EventType = "work_item.ingested"
	EventWorkItemPlanning     EventType = "work_item.planning"
	EventWorkItemPlanReview   EventType = "work_item.plan_review"
	EventWorkItemApproved     EventType = "work_item.approved"
	EventWorkItemImplementing EventType = "work_item.implementing"
	EventWorkItemReviewing    EventType = "work_item.reviewing"
	EventWorkItemCompleted    EventType = "work_item.completed"
	EventWorkItemFailed       EventType = "work_item.failed"

	// Workspace events
	EventWorkspaceCreated EventType = "workspace.created"

	// Plan events
	EventPlanGenerated          EventType = "plan.generated"
	EventPlanSubmittedForReview EventType = "plan.submitted_for_review"
	EventPlanApproved           EventType = "plan.approved"
	EventPlanRejected           EventType = "plan.rejected"
	EventPlanRevised            EventType = "plan.revised"
	EventPlanFailed             EventType = "plan.failed"

	// Implementation events
	EventImplementationStarted EventType = "work_item.implementation_started"

	// Worktree events
	EventWorktreeRemoved EventType = "worktree.removed"

	// Agent session events
	EventAgentSessionStarted     EventType = "agent_session.started"
	EventAgentSessionCompleted   EventType = "agent_session.completed"
	EventAgentSessionFailed      EventType = "agent_session.failed"
	EventAgentSessionInterrupted EventType = "agent_session.interrupted"
	EventAgentSessionResumed     EventType = "agent_session.resumed"

	// Question events
	EventAgentQuestionRaised   EventType = "agent_question.raised"
	EventAgentQuestionAnswered EventType = "agent_question.answered"

	// Review events
	EventReviewStarted           EventType = "review.started"
	EventReviewCompleted         EventType = "review.completed"
	EventCritiquesFound          EventType = "review.critiques_found"
	EventReimplementationStarted EventType = "reimplementation.started"
	EventReviewArtifactRecorded  EventType = "review.artifact_recorded"

	// Adapter error events
	EventAdapterError EventType = "adapter.error"
)

Regular events - persisted first, then dispatched to subscribers

type FAQEntry 

type FAQEntry struct {
	ID             string
	PlanID         string
	AgentSessionID string
	RepoName       string
	Question       string
	Answer         string
	AnsweredBy     string
	CreatedAt      time.Time
}

FAQEntry represents a question-answer pair from the foreman.

type GithubPullRequest 

type GithubPullRequest struct {
	ID         string
	Owner      string
	Repo       string
	Number     int
	State      string
	Draft      bool
	HeadBranch string
	HTMLURL    string
	MergedAt   *time.Time
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

GithubPullRequest is the durable row for a GitHub PR.

type GitlabMergeRequest 

type GitlabMergeRequest struct {
	ID           string
	ProjectPath  string
	IID          int
	State        string
	Draft        bool
	SourceBranch string
	WebURL       string
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

GitlabMergeRequest is the durable row for a GitLab MR.

type NewSessionFilter 

type NewSessionFilter struct {
	ID          string
	WorkspaceID string
	Name        string
	Provider    string
	Criteria    NewSessionFilterCriteria
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

NewSessionFilter persists a named New Session filter for a workspace/provider.

type NewSessionFilterCriteria 

type NewSessionFilterCriteria struct {
	Scope      SelectionScope
	View       string
	State      string
	Search     string
	Labels     []string
	Owner      string
	Repository string
	Group      string
	TeamID     string
}

NewSessionFilterCriteria captures persisted New Session overlay filter criteria.

type NewSessionFilterLock 

type NewSessionFilterLock struct {
	FilterID       string
	InstanceID     string
	LeaseExpiresAt time.Time
	AcquiredAt     time.Time
	UpdatedAt      time.Time
}

NewSessionFilterLock coordinates lease ownership while applying a New Session filter.

type ParseErrors 

type ParseErrors struct {
	// MissingBlock is true if the substrate-plan YAML block was not found.
	MissingBlock bool
	// InvalidYAML is true if the YAML block could not be parsed.
	InvalidYAML bool
	// YAMLParseError contains the YAML parsing error message if InvalidYAML is true.
	YAMLParseError string
	// UnknownRepos contains repo names in YAML but not in workspace.
	UnknownRepos []string
	// MissingSubPlans contains repo names in YAML but no matching section found.
	MissingSubPlans []string
	// UndeclaredSubPlans contains section headings for repos not in YAML.
	UndeclaredSubPlans []string
	// EmptyExecutionGroups is true if execution_groups is empty or missing.
	EmptyExecutionGroups bool
	// MissingOrchestration is true if the Orchestration section is absent or empty.
	MissingOrchestration bool
	// IncompleteSubPlans contains repo-scoped quality issues for thin or malformed sub-plans.
	IncompleteSubPlans []string
}

ParseErrors represents errors encountered during plan parsing.

func (ParseErrors) Error 

func (e ParseErrors) Error() string

Error implements the error interface.

func (ParseErrors) HasErrors 

func (e ParseErrors) HasErrors() bool

HasErrors returns true if any parse errors are present.

type Plan 

type Plan struct {
	ID               string
	WorkItemID       string
	Status           PlanStatus
	OrchestratorPlan string
	Version          int
	FAQ              []FAQEntry
	CreatedAt        time.Time
	UpdatedAt        time.Time
}

Plan is the orchestration plan for a work item.

type PlanStatus 

type PlanStatus string

PlanStatus represents the lifecycle state of a plan. 

const (
	PlanDraft         PlanStatus = "draft"
	PlanPendingReview PlanStatus = "pending_review"
	PlanApproved      PlanStatus = "approved"
	PlanRejected      PlanStatus = "rejected"
	PlanSuperseded    PlanStatus = "superseded"
)

type PlanningContext 

type PlanningContext struct {
	// WorkItem is the work item being planned.
	WorkItem WorkItemSnapshot
	// WorkspaceAgentsMd is the content of the workspace-root AGENTS.md file. Empty if absent.
	WorkspaceAgentsMd string
	// Repos is the list of discovered git-work repositories.
	Repos []RepoPointer
	// SessionID is the ULID for this planning session.
	SessionID string
	// SessionDraftPath is the absolute path to plan-draft.md for this session.
	SessionDraftPath string
	// MaxParseRetries is the maximum number of correction attempts (from config).
	MaxParseRetries int
	// RevisionFeedback is the human's feedback when requesting plan changes.
	// Empty for initial planning sessions.
	RevisionFeedback string
	// CurrentPlanText is the previous plan content for revision context.
	// Empty for initial planning sessions.
	CurrentPlanText string
	// PriorSessionID is the Substrate task ID of the prior planning session.
	// Set for revision runs so the harness can link resume data.
	PriorSessionID string
	// PriorResumeInfo holds harness-specific resume data from the prior planning session.
	// Set for revision runs when the prior session produced resume data. Nil otherwise.
	PriorResumeInfo map[string]string
}

PlanningContext contains all information needed to run a planning session.

type PlanningResult 

type PlanningResult struct {
	// Plan is the generated plan (nil if planning failed).
	Plan *Plan
	// SubPlans is the list of generated sub-plans.
	SubPlans []TaskPlan
	// Warnings is the list of non-fatal warnings.
	Warnings []PlanningWarning
	// ParseErrors contains parsing errors if the plan could not be parsed.
	ParseErrors *ParseErrors
	// Retries is the number of correction attempts made.
	Retries int
}

PlanningResult contains the result of a planning pipeline run.

type PlanningWarning 

type PlanningWarning struct {
	// Type is the warning type (e.g., "plain_git_clone", "pull_failed").
	Type string
	// Message is a human-readable description.
	Message string
	// Path is the affected path (if applicable).
	Path string
}

PlanningWarning represents a non-fatal issue discovered during planning.

type PullFailure 

type PullFailure struct {
	// RepoName is the repository name.
	RepoName string
	// Error is the error message.
	Error string
}

PullFailure represents a failed git pull operation.

type Question 

type Question struct {
	ID             string
	AgentSessionID string
	Content        string
	Context        string
	Answer         string
	ProposedAnswer string
	AnsweredBy     string
	Status         QuestionStatus
	CreatedAt      time.Time
	AnsweredAt     *time.Time
}

Question is a question surfaced by a sub-agent, routed through the foreman.

type QuestionStatus 

type QuestionStatus string

QuestionStatus represents the lifecycle state of a question. 

const (
	QuestionPending   QuestionStatus = "pending"
	QuestionAnswered  QuestionStatus = "answered"
	QuestionEscalated QuestionStatus = "escalated"
)

type RawPlanOutput 

type RawPlanOutput struct {
	// ExecutionGroups is a list of repo groups that can run in parallel.
	// repos in group 0 run first (parallel), then group 1, etc.
	ExecutionGroups [][]string
	// Orchestration is the cross-repo coordination section content.
	Orchestration string
	// SubPlans is the list of parsed sub-plan sections.
	SubPlans []RawSubPlan
	// RawContent is the full markdown content of the plan.
	RawContent string
}

RawPlanOutput represents the parsed output from a planning agent.

type RawSubPlan 

type RawSubPlan struct {
	// RepoName is the repository name from the section heading.
	RepoName string
	// Content is the full markdown content of the sub-plan section.
	Content string
}

RawSubPlan represents a parsed sub-plan section from the planning output.

type RepoPointer 

type RepoPointer struct {
	// Name is the directory name of the repository.
	Name string
	// Path is the absolute path to the repository root.
	Path string
	// MainDir is the absolute path to the main/ worktree.
	MainDir string
	// Language is the detected primary language (e.g., "go", "typescript", "python").
	Language string
	// Framework is the detected framework (e.g., "gin", "next", "fastapi"). Empty if not detected.
	Framework string
	// AgentsMdPath is the absolute path to AGENTS.md if present in the main worktree. Empty if absent.
	AgentsMdPath string
	// DocPaths are configured documentation paths from repo config. Nil if none.
	DocPaths []string
}

RepoPointer contains information about a discovered git-work repository.

type RepoRef 

type RepoRef struct {
	Provider  string `json:"provider"`
	Host      string `json:"host,omitempty"`
	Owner     string `json:"owner,omitempty"`
	Repo      string `json:"repo,omitempty"`
	ProjectID int64  `json:"project_id,omitempty"`
	URL       string `json:"url,omitempty"`
}

type ReviewArtifact 

type ReviewArtifact struct {
	Provider     string    `json:"provider"`
	Kind         string    `json:"kind"`
	RepoName     string    `json:"repo_name"`
	Ref          string    `json:"ref"`
	URL          string    `json:"url,omitempty"`
	State        string    `json:"state,omitempty"`
	Branch       string    `json:"branch,omitempty"`
	WorktreePath string    `json:"worktree_path,omitempty"`
	Draft        bool      `json:"draft,omitempty"`
	UpdatedAt    time.Time `json:"updated_at,omitzero"`
}

ReviewArtifact is durable UI-facing PR/MR metadata for a repo task.

type ReviewArtifactEventPayload 

type ReviewArtifactEventPayload struct {
	WorkItemID string         `json:"work_item_id"`
	Artifact   ReviewArtifact `json:"artifact"`
}

ReviewArtifactEventPayload persists a review artifact against a work item.

type ReviewCycle 

type ReviewCycle struct {
	ID              string
	CycleNumber     int
	AgentSessionID  string
	ReviewerHarness string
	Summary         string
	Status          ReviewCycleStatus
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

ReviewCycle is one review pass over an agent session's output.

type ReviewCycleStatus 

type ReviewCycleStatus string

ReviewCycleStatus represents the lifecycle state of a review cycle. 

const (
	ReviewCycleReviewing      ReviewCycleStatus = "reviewing"
	ReviewCycleCritiquesFound ReviewCycleStatus = "critiques_found"
	ReviewCycleReimplementing ReviewCycleStatus = "reimplementing"
	ReviewCyclePassed         ReviewCycleStatus = "passed"
	ReviewCycleFailed         ReviewCycleStatus = "failed"
)

type ReviewRef 

type ReviewRef struct {
	BaseRepo   RepoRef `json:"base_repo"`
	HeadRepo   RepoRef `json:"head_repo"`
	BaseBranch string  `json:"base_branch,omitempty"`
	HeadBranch string  `json:"head_branch,omitempty"`
}

type SelectionScope 

type SelectionScope string

SelectionScope identifies the granularity of a work item selection. 

const (
	ScopeIssues      SelectionScope = "issues"
	ScopeProjects    SelectionScope = "projects"
	ScopeInitiatives SelectionScope = "initiatives"
	ScopeManual      SelectionScope = "manual"
)

type Session 

type Session struct {
	ID            string
	WorkspaceID   string
	ExternalID    string
	Source        string
	Title         string
	Description   string
	Labels        []string
	AssigneeID    string
	State         SessionState
	Metadata      map[string]any
	ExtraContext  string
	SourceScope   SelectionScope
	SourceItemIDs []string
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

Session is the root aggregate representing an external ticket.

type SessionDirInfo 

type SessionDirInfo struct {
	// Path is the absolute path to the session directory.
	Path string
	// DraftPath is the absolute path to plan-draft.md.
	DraftPath string
	// Exists is true if the directory already exists.
	Exists bool
}

SessionDirInfo contains information about a planning session directory.

type SessionHistoryEntry 

type SessionHistoryEntry struct {
	SessionID          string
	WorkspaceID        string
	WorkspaceName      string
	WorkItemID         string
	WorkItemExternalID string
	WorkItemTitle      string
	WorkItemState      SessionState
	RepositoryName     string
	HarnessName        string
	Status             TaskStatus
	AgentSessionCount  int
	HasOpenQuestion    bool
	HasInterrupted     bool
	CreatedAt          time.Time
	UpdatedAt          time.Time
	CompletedAt        *time.Time
}

SessionHistoryEntry is one searchable root-session result.

The work item is the primary session identity shown in session history. When the work item has child tasks, SessionID/RepositoryName/HarnessName/Status describe the latest contributing task for preview purposes.

type SessionHistoryFilter 

type SessionHistoryFilter struct {
	WorkspaceID *string
	Search      string
	Limit       int
	Offset      int
}

SessionHistoryFilter constrains session-history search results.

type SessionReviewArtifact 

type SessionReviewArtifact struct {
	ID                 string
	WorkspaceID        string
	WorkItemID         string
	Provider           string
	ProviderArtifactID string
	CreatedAt          time.Time
	UpdatedAt          time.Time
}

SessionReviewArtifact links a work item to a provider-specific PR/MR record.

type SessionState 

type SessionState string

SessionState represents the lifecycle state of a work item. 

const (
	SessionIngested     SessionState = "ingested"
	SessionPlanning     SessionState = "planning"
	SessionPlanReview   SessionState = "plan_review"
	SessionApproved     SessionState = "approved"
	SessionImplementing SessionState = "implementing"
	SessionReviewing    SessionState = "reviewing"
	SessionCompleted    SessionState = "completed"
	SessionFailed       SessionState = "failed"
)

type SourceMetadataField 

type SourceMetadataField struct {
	Label string `json:"label"`
	Value string `json:"value"`
}

SourceMetadataField is one durable metadata row for a source item snapshot.

type SourceSummary 

type SourceSummary struct {
	Provider    string                `json:"provider"`
	Kind        string                `json:"kind,omitempty"`
	Ref         string                `json:"ref"`
	Title       string                `json:"title,omitempty"`
	Description string                `json:"description,omitempty"`
	Excerpt     string                `json:"excerpt,omitempty"`
	State       string                `json:"state,omitempty"`
	Labels      []string              `json:"labels,omitempty"`
	Container   string                `json:"container,omitempty"`
	URL         string                `json:"url,omitempty"`
	CreatedAt   *time.Time            `json:"created_at,omitempty"`
	UpdatedAt   *time.Time            `json:"updated_at,omitempty"`
	Metadata    []SourceMetadataField `json:"metadata,omitempty"`
}

SourceSummary is a durable per-source-item snapshot for sessions sourced from trackers.

type SubstrateInstance 

type SubstrateInstance struct {
	ID            string
	WorkspaceID   string
	PID           int
	Hostname      string
	LastHeartbeat time.Time
	StartedAt     time.Time
}

SubstrateInstance is a running Substrate process registered for a workspace.

type SystemEvent 

type SystemEvent struct {
	ID          string
	EventType   string
	WorkspaceID string
	Payload     string
	CreatedAt   time.Time
}

SystemEvent is a persisted system event for audit and replay.

type Task 

type Task struct {
	ID              string
	WorkItemID      string
	WorkspaceID     string
	Phase           TaskPhase
	SubPlanID       string
	PlanID          string // Plan produced by this planning session (empty for non-planning tasks).
	RepositoryName  string
	WorktreePath    string
	HarnessName     string
	Status          TaskStatus
	PID             *int
	StartedAt       *time.Time
	CompletedAt     *time.Time
	ShutdownAt      *time.Time
	ExitCode        *int
	OwnerInstanceID *string
	CreatedAt       time.Time
	UpdatedAt       time.Time
	ResumeInfo      map[string]string
}

Task is a single child agent session for a work item.

type TaskPhase 

type TaskPhase string

TaskPhase identifies the kind of child agent session being tracked. 

const (
	TaskPhasePlanning       TaskPhase = "planning"
	TaskPhaseImplementation TaskPhase = "implementation"
	TaskPhaseReview         TaskPhase = "review"
)

type TaskPlan 

type TaskPlan struct {
	ID             string
	PlanID         string
	RepositoryName string
	Content        string
	Order          int
	Status         TaskPlanStatus
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

TaskPlan is a single repository's portion of the plan.

type TaskPlanStatus 

type TaskPlanStatus string

TaskPlanStatus represents the lifecycle state of a task plan. 

const (
	SubPlanPending    TaskPlanStatus = "pending"
	SubPlanInProgress TaskPlanStatus = "in_progress"
	SubPlanCompleted  TaskPlanStatus = "completed"
	SubPlanFailed     TaskPlanStatus = "failed"
)

type TaskStatus 

type TaskStatus string

TaskStatus represents the lifecycle state of an agent session. 

const (
	AgentSessionPending          TaskStatus = "pending"
	AgentSessionRunning          TaskStatus = "running"
	AgentSessionWaitingForAnswer TaskStatus = "waiting_for_answer"
	AgentSessionCompleted        TaskStatus = "completed"
	AgentSessionInterrupted      TaskStatus = "interrupted"
	AgentSessionFailed           TaskStatus = "failed"
)

type TrackerReference 

type TrackerReference struct {
	Provider   string  `json:"provider"`
	Kind       string  `json:"kind"`
	ID         string  `json:"id"`
	URL        string  `json:"url,omitempty"`
	Owner      string  `json:"owner,omitempty"`
	Repo       string  `json:"repo,omitempty"`
	ProjectID  int64   `json:"project_id,omitempty"`
	Number     int64   `json:"number,omitempty"`
	Repository RepoRef `json:"repository,omitzero"`
}

type TrackerState 

type TrackerState string

TrackerState represents the state of a work item in an external tracker. This is distinct from WorkItemState which is Substrate's internal state machine. Adapters map TrackerState to their native states (e.g., Linear workflow states). 

const (
	TrackerStateTodo       TrackerState = "todo"
	TrackerStateInProgress TrackerState = "in_progress"
	TrackerStateInReview   TrackerState = "in_review"
	TrackerStateDone       TrackerState = "done"
)

type WorkItemSnapshot 

type WorkItemSnapshot struct {
	ID           string
	ExternalID   string
	Title        string
	Description  string
	Labels       []string
	Source       string
	ExtraContext string
}

WorkItemSnapshot is a projection of WorkItem for planning context.

type Workspace 

type Workspace struct {
	ID        string
	Name      string
	RootPath  string
	Status    WorkspaceStatus
	CreatedAt time.Time
	UpdatedAt time.Time
}

Workspace represents a pre-existing folder initialized with substrate init.

type WorkspaceHealthCheck 

type WorkspaceHealthCheck struct {
	// GitWorkRepos is the list of git-work initialized repositories (paths).
	GitWorkRepos []string
	// PlainGitClones is the list of plain git clones (warnings).
	PlainGitClones []string
	// PullFailures is the list of repos where git pull failed.
	PullFailures []PullFailure
}

WorkspaceHealthCheck contains the result of a workspace health scan.

func (WorkspaceHealthCheck) ToPlanningWarnings 

func (c WorkspaceHealthCheck) ToPlanningWarnings() []PlanningWarning

ToPlanningWarnings converts the health check issues to warnings.

type WorkspaceStatus 

type WorkspaceStatus string

WorkspaceStatus represents the lifecycle state of a workspace. 

const (
	WorkspaceCreating WorkspaceStatus = "creating"
	WorkspaceReady    WorkspaceStatus = "ready"
	WorkspaceArchived WorkspaceStatus = "archived"
	WorkspaceError    WorkspaceStatus = "error"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.