types

package
v0.54.0 Latest Latest
Warning

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

 Go to latest Published: Jun 2, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package types defines core data structures for the bd issue tracker.

Package types defines core data structures for the bd issue tracker.

Index

Constants

View Source 
const (
	WaitsForAllChildren = "all-children" // Wait for all dynamic children to complete
	WaitsForAnyChildren = "any-children" // Proceed when first child completes (future)
)

WaitsForGate constants

View Source 
const (
	BondTypeSequential  = "sequential"  // B runs after A completes
	BondTypeParallel    = "parallel"    // B runs alongside A
	BondTypeConditional = "conditional" // B runs only if A fails
	BondTypeRoot        = "root"        // Marks the primary/root component
)

Bond type constants for compound molecules

View Source 
const (
	ValidationAccepted          = "accepted"
	ValidationRejected          = "rejected"
	ValidationRevisionRequested = "revision_requested"
)

Validation outcome constants

View Source 
const ClockSkewGrace = 1 * time.Hour

ClockSkewGrace is added to TTL to handle clock drift between machines

View Source 
const DefaultTombstoneTTL = 30 * 24 * time.Hour

DefaultTombstoneTTL is the default time-to-live for tombstones (30 days)

View Source 
const MaxHierarchyDepth = 3

MaxHierarchyDepth is the maximum nesting level for hierarchical IDs. Prevents over-decomposition and keeps IDs manageable.

View Source 
const MinTombstoneTTL = 7 * 24 * time.Hour

MinTombstoneTTL is the minimum allowed TTL (7 days) to prevent data loss

Variables

View Source 
var FailureCloseKeywords = []string{
	"failed",
	"rejected",
	"wontfix",
	"won't fix",
	"canceled",
	"cancelled",
	"abandoned",
	"blocked",
	"error",
	"timeout",
	"aborted",
}

FailureCloseKeywords are keywords that indicate an issue was closed due to failure. Used by conditional-blocks dependencies to determine if the condition is met.

Functions

func CheckHierarchyDepth 

func CheckHierarchyDepth(parentID string, maxDepth int) error

CheckHierarchyDepth validates that adding a child to parentID won't exceed maxDepth. Returns an error if the depth would be exceeded. If maxDepth < 1, it defaults to MaxHierarchyDepth.

func GenerateChildID 

func GenerateChildID(parentID string, childNumber int) string

GenerateChildID creates a hierarchical child ID. Format: parent.N (e.g., "bd-af78e9a2.1", "bd-af78e9a2.1.2")

Max depth: 3 levels (prevents over-decomposition) Max breadth: Unlimited (tested up to 347 children)

func GenerateHashID 

func GenerateHashID(prefix, title, description string, created time.Time, workspaceID string) string

GenerateHashID creates a deterministic content-based hash ID. Format: prefix-{6-8-char-hex} with progressive extension on collision Examples: bd-a3f2dd (6), bd-a3f2dda (7), bd-a3f2dda8 (8)

The hash is computed from: - Title (primary identifier) - Description (additional context) - Created timestamp (RFC3339Nano for precision) - Workspace ID (prevents cross-workspace collisions)

Returns the full 64-char hash for progressive collision handling. Caller extracts hash[:6] initially, then hash[:7], hash[:8] on collisions.

Collision probability with 6 chars (24 bits): - 1,000 issues: ~2.94% chance (most extend to 7 chars) - 10,000 issues: ~94.9% chance (most extend to 7-8 chars)

Progressive strategy optimizes for common case: 97% stay at 6 chars.

func IsFailureClose 

func IsFailureClose(closeReason string) bool

IsFailureClose returns true if the close reason indicates the issue failed. This is used by conditional-blocks dependencies: B runs only if A fails. A "failure" close reason contains one of the FailureCloseKeywords (case-insensitive).

func IsProcessAlive 

func IsProcessAlive(pid int, hostname string) bool

IsProcessAlive checks if a process with the given PID is alive on the given hostname. If hostname doesn't match the current host, it returns true (cannot verify remote, assume alive). If hostname matches the current host, it checks if the PID exists. Permission errors are treated as "alive" (fail-safe: better to skip than wrongly remove a lock).

func ParseHierarchicalID 

func ParseHierarchicalID(id string) (rootID, parentID string, depth int)

ParseHierarchicalID extracts the parent ID and depth from a hierarchical ID. Returns: (rootID, parentID, depth)

Examples: 

"bd-af78e9a2" → ("bd-af78e9a2", "", 0)
"bd-af78e9a2.1" → ("bd-af78e9a2", "bd-af78e9a2", 1)
"bd-af78e9a2.1.2" → ("bd-af78e9a2", "bd-af78e9a2.1", 2)

func ShouldSkipDatabase 

func ShouldSkipDatabase(beadsDir string) (skip bool, holder string, err error)

ShouldSkipDatabase checks if the given beads directory has an exclusive lock file. It returns true if the database should be skipped (lock is valid and holder is alive), false otherwise. It also returns the lock holder name if skipping, and any error encountered.

The function will: - Return false if no lock file exists (proceed with database) - Return true if lock exists and holder process is alive (skip database) - Remove stale locks (dead process) and return false (proceed with database) - Return true on malformed locks (fail-safe, skip database)

Types

type AgentState 

type AgentState string

AgentState represents the self-reported state of an agent 

const (
	StateIdle     AgentState = "idle"     // Agent is waiting for work
	StateSpawning AgentState = "spawning" // Agent is starting up
	StateRunning  AgentState = "running"  // Agent is executing (general)
	StateWorking  AgentState = "working"  // Agent is actively working on a task
	StateStuck    AgentState = "stuck"    // Agent is blocked and needs help
	StateDone     AgentState = "done"     // Agent completed its current work
	StateStopped  AgentState = "stopped"  // Agent has cleanly shut down
	StateDead     AgentState = "dead"     // Agent died without clean shutdown (timeout detection)
)

Agent state constants

func (AgentState) IsValid 

func (s AgentState) IsValid() bool

IsValid checks if the agent state value is valid

type AliasRecord added in v0.53.1 

type AliasRecord struct {
	AliasName     string `json:"alias_name"`
	CanonicalName string `json:"canonical_name"`
}

AliasRecord represents a sticky entity alias for repository-wide sharing

type AttestsMeta 

type AttestsMeta struct {
	// Skill is the identifier of the skill being attested (e.g., "go", "rust", "code-review")
	Skill string `json:"skill"`
	// Level is the proficiency level (e.g., "beginner", "intermediate", "expert", or numeric 1-5)
	Level string `json:"level"`
	// Date is when the attestation was made (RFC3339 format)
	Date string `json:"date"`
	// Evidence is optional reference to supporting evidence (e.g., issue ID, commit, PR)
	Evidence string `json:"evidence,omitempty"`
	// Notes is optional free-form notes about the attestation
	Notes string `json:"notes,omitempty"`
}

AttestsMeta holds metadata for attests dependencies (skill attestations). Stored as JSON in the Dependency.Metadata field. Enables: Entity X attests that Entity Y has skill Z at level N.

type BlockedIssue 

type BlockedIssue struct {
	Issue
	BlockedByCount int      `json:"blocked_by_count"`
	BlockedBy      []string `json:"blocked_by"`
}

BlockedIssue extends Issue with blocking information

type BondRef 

type BondRef struct {
	SourceID  string `json:"source_id"`            // Source proto or molecule ID
	BondType  string `json:"bond_type"`            // sequential, parallel, conditional
	BondPoint string `json:"bond_point,omitempty"` // Attachment site (issue ID or empty for root)
}

BondRef tracks compound molecule lineage. When protos or molecules are bonded together, BondRefs record which sources were combined and how they were attached.

type BranchCache 

type BranchCache struct {
	BranchName       string    `json:"branch_name"`
	LastValidatedSHA string    `json:"last_validated_sha"`
	IsMerged         bool      `json:"is_merged"`
	IsDeleted        bool      `json:"is_deleted"`
	LastCheckedAt    time.Time `json:"last_checked_at"`
}

BranchCache represents cached Git facts about a branch

type BranchState 

type BranchState struct {
	ID            int64          `json:"id"`
	State         LifecycleState `json:"state"`
	ScopeType     ScopeType      `json:"scope_type"`
	ScopeRef      string         `json:"scope_ref"`
	ShortReason   string         `json:"short_reason"`
	FullReasonRef string         `json:"full_reason_ref"` // Link to the special devlog entry ID
	Actor         string         `json:"actor"`
	Timestamp     time.Time      `json:"timestamp"`
	CommitSHA     string         `json:"commit_sha"`
	BranchRef     string         `json:"branch_ref"`
}

BranchState represents a manually set state for a specific scope (e.g. branch, entity)

type Comment 

type Comment struct {
	ID        int64     `json:"id"`
	IssueID   string    `json:"issue_id"`
	Author    string    `json:"author"`
	Text      string    `json:"text"`
	CreatedAt time.Time `json:"created_at"`
}

Comment represents a comment on an issue

type Dependency 

type Dependency struct {
	IssueID     string         `json:"issue_id"`
	DependsOnID string         `json:"depends_on_id"`
	Type        DependencyType `json:"type"`
	CreatedAt   time.Time      `json:"created_at"`
	CreatedBy   string         `json:"created_by,omitempty"`
	// Metadata contains type-specific edge data (JSON blob)
	// Examples: similarity scores, approval details, skill proficiency
	Metadata string `json:"metadata,omitempty"`
	// ThreadID groups conversation edges for efficient thread queries
	// For replies-to edges, this identifies the conversation root
	ThreadID string `json:"thread_id,omitempty"`
}

Dependency represents a relationship between issues

type DependencyCounts 

type DependencyCounts struct {
	DependencyCount int `json:"dependency_count"` // Number of issues this issue depends on
	DependentCount  int `json:"dependent_count"`  // Number of issues that depend on this issue
}

DependencyCounts holds counts for dependencies and dependents

type DependencyType 

type DependencyType string

DependencyType categorizes the relationship 

const (
	// Workflow types (affect ready work calculation)
	DepBlocks            DependencyType = "blocks"
	DepParentChild       DependencyType = "parent-child"
	DepConditionalBlocks DependencyType = "conditional-blocks" // B runs only if A fails
	DepWaitsFor          DependencyType = "waits-for"          // Fanout gate: wait for dynamic children

	// Association types
	DepRelated        DependencyType = "related"
	DepDiscoveredFrom DependencyType = "discovered-from"

	// Graph link types
	DepRepliesTo  DependencyType = "replies-to" // Conversation threading
	DepRelatesTo  DependencyType = "relates-to" // Loose knowledge graph edges
	DepDuplicates DependencyType = "duplicates" // Deduplication link
	DepSupersedes DependencyType = "supersedes" // Version chain link

	// Entity types (HOP foundation - Decision 004)
	DepAuthoredBy DependencyType = "authored-by" // Creator relationship
	DepAssignedTo DependencyType = "assigned-to" // Assignment relationship
	DepApprovedBy DependencyType = "approved-by" // Approval relationship
	DepAttests    DependencyType = "attests"     // Skill attestation: X attests Y has skill Z

	// Convoy tracking (non-blocking cross-project references)
	DepTracks DependencyType = "tracks" // Convoy → issue tracking (non-blocking)

	// Reference types (cross-referencing without blocking)
	DepUntil     DependencyType = "until"     // Active until target closes (e.g., muted until issue resolved)
	DepCausedBy  DependencyType = "caused-by" // Triggered by target (audit trail)
	DepValidates DependencyType = "validates" // Approval/validation relationship

	// Delegation types (work delegation chains)
	DepDelegatedFrom DependencyType = "delegated-from" // Work delegated from parent; completion cascades up
)

Dependency type constants

func (DependencyType) AffectsReadyWork 

func (d DependencyType) AffectsReadyWork() bool

AffectsReadyWork returns true if this dependency type blocks work. Only blocking types affect the ready work calculation.

func (DependencyType) IsValid 

func (d DependencyType) IsValid() bool

IsValid checks if the dependency type value is valid. Accepts any non-empty string up to 50 characters. Use IsWellKnown() to check if it's a built-in type.

func (DependencyType) IsWellKnown 

func (d DependencyType) IsWellKnown() bool

IsWellKnown checks if the dependency type is a well-known constant. Returns false for custom/user-defined types (which are still valid).

type EntityRef 

type EntityRef struct {
	// Name is the human-readable identifier (e.g., "polecat/Nux", "mayor")
	Name string `json:"name,omitempty"`

	// Platform identifies the execution context (e.g., "gastown", "github")
	Platform string `json:"platform,omitempty"`

	// Org identifies the organization (e.g., "steveyegge", "anthropics")
	Org string `json:"org,omitempty"`

	// ID is the unique identifier within the platform/org (e.g., "polecat-nux")
	ID string `json:"id,omitempty"`
}

EntityRef is a structured reference to an entity (human, agent, or org). This is the foundation for HOP entity tracking and CV chains. Can be rendered as a URI: entity://hop/<platform>/<org>/<id>

Example usage: 

ref := &EntityRef{
    Name:     "polecat/Nux",
    Platform: "gastown",
    Org:      "steveyegge",
    ID:       "polecat-nux",
}
uri := ref.URI() // "entity://hop/gastown/steveyegge/polecat-nux"

func ParseEntityURI 

func ParseEntityURI(uri string) (*EntityRef, error)

ParseEntityURI parses a HOP entity URI into an EntityRef. Format: entity://hop/<platform>/<org>/<id> Returns nil and error if the URI is invalid.

func (*EntityRef) IsEmpty 

func (e *EntityRef) IsEmpty() bool

IsEmpty returns true if all fields are empty.

func (*EntityRef) String 

func (e *EntityRef) String() string

String returns a human-readable representation. Prefers Name if set, otherwise returns URI or ID.

func (*EntityRef) URI 

func (e *EntityRef) URI() string

URI returns the entity as a HOP URI. Format: entity://hop/<platform>/<org>/<id> Returns empty string if Platform, Org, or ID is missing.

type EpicStatus 

type EpicStatus struct {
	Epic             *Issue `json:"epic"`
	TotalChildren    int    `json:"total_children"`
	ClosedChildren   int    `json:"closed_children"`
	EligibleForClose bool   `json:"eligible_for_close"`
}

EpicStatus represents an epic with its completion status

type Event 

type Event struct {
	ID        int64     `json:"id"`
	IssueID   string    `json:"issue_id"`
	EventType EventType `json:"event_type"`
	Actor     string    `json:"actor"`
	OldValue  *string   `json:"old_value,omitempty"`
	NewValue  *string   `json:"new_value,omitempty"`
	Comment   *string   `json:"comment,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

Event represents an audit trail entry

type EventType 

type EventType string

EventType categorizes audit trail events 

const (
	EventCreated           EventType = "created"
	EventUpdated           EventType = "updated"
	EventStatusChanged     EventType = "status_changed"
	EventCommented         EventType = "commented"
	EventClosed            EventType = "closed"
	EventReopened          EventType = "reopened"
	EventDependencyAdded   EventType = "dependency_added"
	EventDependencyRemoved EventType = "dependency_removed"
	EventLabelAdded        EventType = "label_added"
	EventLabelRemoved      EventType = "label_removed"
	EventCompacted         EventType = "compacted"
)

Event type constants for audit trail

type ExclusiveLock 

type ExclusiveLock struct {
	Holder    string    `json:"holder"`     // Name of lock holder (e.g., "vc-executor")
	PID       int       `json:"pid"`        // Process ID
	Hostname  string    `json:"hostname"`   // Hostname where process is running
	StartedAt time.Time `json:"started_at"` // When lock was acquired
	Version   string    `json:"version"`    // Version of lock holder
}

ExclusiveLock represents the lock file format for external tools to claim exclusive management of a beads database. When this lock is present, the bd daemon will skip the database in its sync cycle.

func NewExclusiveLock 

func NewExclusiveLock(holder, version string) (*ExclusiveLock, error)

NewExclusiveLock creates a new exclusive lock for the current process

func (*ExclusiveLock) MarshalJSON 

func (e *ExclusiveLock) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler

func (*ExclusiveLock) UnmarshalJSON 

func (e *ExclusiveLock) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler

func (*ExclusiveLock) Validate 

func (e *ExclusiveLock) Validate() error

Validate checks if the lock has valid field values

type Issue 

type Issue struct {
	// ===== Core Identification =====
	ID          string `json:"id"`
	ContentHash string `json:"-"` // Internal: SHA256 of canonical content - NOT exported to JSONL

	// ===== Issue Content =====
	Title              string `json:"title"`
	Description        string `json:"description,omitempty"`
	Design             string `json:"design,omitempty"`
	AcceptanceCriteria string `json:"acceptance_criteria,omitempty"`
	Notes              string `json:"notes,omitempty"`

	// ===== Status & Workflow =====
	Status    Status    `json:"status,omitempty"`
	Priority  int       `json:"priority"` // No omitempty: 0 is valid (P0/critical)
	IssueType IssueType `json:"issue_type,omitempty"`

	// ===== Assignment =====
	Assignee         string `json:"assignee,omitempty"`
	Owner            string `json:"owner,omitempty"` // Human owner for CV attribution (git author email)
	EstimatedMinutes *int   `json:"estimated_minutes,omitempty"`

	// ===== Timestamps =====
	CreatedAt       time.Time  `json:"created_at"`
	CreatedBy       string     `json:"created_by,omitempty"` // Who created this issue (GH#748)
	UpdatedAt       time.Time  `json:"updated_at"`
	ClosedAt        *time.Time `json:"closed_at,omitempty"`
	CloseReason     string     `json:"close_reason,omitempty"`      // Reason provided when closing
	ClosedBySession string     `json:"closed_by_session,omitempty"` // Claude Code session that closed this issue

	// ===== Time-Based Scheduling (GH#820) =====
	DueAt      *time.Time `json:"due_at,omitempty"`      // When this issue should be completed
	DeferUntil *time.Time `json:"defer_until,omitempty"` // Hide from bd ready until this time

	// ===== External Integration =====
	ExternalRef  *string `json:"external_ref,omitempty"`  // e.g., "gh-9", "jira-ABC"
	SourceSystem string  `json:"source_system,omitempty"` // Adapter/system that created this issue (federation)

	// ===== Compaction Metadata =====
	CompactionLevel   int        `json:"compaction_level,omitempty"`
	CompactedAt       *time.Time `json:"compacted_at,omitempty"`
	CompactedAtCommit *string    `json:"compacted_at_commit,omitempty"` // Git commit hash when compacted
	OriginalSize      int        `json:"original_size,omitempty"`

	// ===== Internal Routing (not exported to JSONL) =====
	SourceRepo string `json:"-"` // Which repo owns this issue (multi-repo support)
	IDPrefix   string `json:"-"` // Override prefix for ID generation

	// ===== Relational Data (populated for export/import) =====
	Labels       []string      `json:"labels,omitempty"`
	Dependencies []*Dependency `json:"dependencies,omitempty"`
	Comments     []*Comment    `json:"comments,omitempty"`

	// ===== Tombstone Fields (soft-delete support) =====
	DeletedAt    *time.Time `json:"deleted_at,omitempty"`    // When deleted
	DeletedBy    string     `json:"deleted_by,omitempty"`    // Who deleted
	DeleteReason string     `json:"delete_reason,omitempty"` // Why deleted
	OriginalType string     `json:"original_type,omitempty"` // Issue type before deletion

	// ===== Messaging Fields (inter-agent communication) =====
	Sender    string `json:"sender,omitempty"`    // Who sent this (for messages)
	Ephemeral bool   `json:"ephemeral,omitempty"` // If true, not exported to JSONL

	// ===== Context Markers =====
	Pinned     bool `json:"pinned,omitempty"`      // Persistent context marker, not a work item
	IsTemplate bool `json:"is_template,omitempty"` // Read-only template molecule

	// ===== Bonding Fields (compound molecule lineage) =====
	BondedFrom []BondRef `json:"bonded_from,omitempty"` // For compounds: constituent protos

	// ===== HOP Fields (entity tracking for CV chains) =====
	Creator      *EntityRef   `json:"creator,omitempty"`       // Who created (human, agent, or org)
	Validations  []Validation `json:"validations,omitempty"`   // Who validated/approved
	QualityScore *float32     `json:"quality_score,omitempty"` // Aggregate quality (0.0-1.0), set by Refineries on merge
	Crystallizes bool         `json:"crystallizes,omitempty"`  // Work that compounds (true: code, features) vs evaporates (false: ops, support) - affects CV weighting per Decision 006

	// ===== Gate Fields (async coordination primitives) =====
	AwaitType string        `json:"await_type,omitempty"` // Condition type: gh:run, gh:pr, timer, human, mail
	AwaitID   string        `json:"await_id,omitempty"`   // Condition identifier (run ID, PR number, etc.)
	Timeout   time.Duration `json:"timeout,omitempty"`    // Max wait time before escalation
	Waiters   []string      `json:"waiters,omitempty"`    // Mail addresses to notify when gate clears

	// ===== Slot Fields (exclusive access primitives) =====
	Holder string `json:"holder,omitempty"` // Who currently holds the slot (empty = available)

	// ===== Source Tracing Fields (formula cooking origin) =====
	SourceFormula  string `json:"source_formula,omitempty"`  // Formula name where step was defined
	SourceLocation string `json:"source_location,omitempty"` // Path: "steps[0]", "advice[0].after"

	// ===== Agent Identity Fields (agent-as-bead support) =====
	HookBead     string     `json:"hook_bead,omitempty"`     // Current work on agent's hook (0..1)
	RoleBead     string     `json:"role_bead,omitempty"`     // Role definition bead (required for agents)
	AgentState   AgentState `json:"agent_state,omitempty"`   // Agent state: idle|running|stuck|stopped
	LastActivity *time.Time `json:"last_activity,omitempty"` // Updated on each action (timeout detection)
	RoleType     string     `json:"role_type,omitempty"`     // Role: polecat|crew|witness|refinery|mayor|deacon
	Rig          string     `json:"rig,omitempty"`           // Rig name (empty for town-level agents)

	// ===== Molecule Type Fields (swarm coordination) =====
	MolType MolType `json:"mol_type,omitempty"` // Molecule type: swarm|patrol|work (empty = work)

	// ===== Work Type Fields (assignment model - Decision 006) =====
	WorkType WorkType `json:"work_type,omitempty"` // Work type: mutex|open_competition (empty = mutex)

	// ===== Event Fields (operational state changes) =====
	EventKind string `json:"event_kind,omitempty"` // Namespaced event type: patrol.muted, agent.started
	Actor     string `json:"actor,omitempty"`      // Entity URI who caused this event
	Target    string `json:"target,omitempty"`     // Entity URI or bead ID affected
	Payload   string `json:"payload,omitempty"`    // Event-specific JSON data
}

Issue represents a trackable work item. Fields are organized into logical groups for maintainability.

func (*Issue) ComputeContentHash 

func (i *Issue) ComputeContentHash() string

ComputeContentHash creates a deterministic hash of the issue's content. Uses all substantive fields (excluding ID, timestamps, and compaction metadata) to ensure that identical content produces identical hashes across all clones.

func (*Issue) GetConstituents 

func (i *Issue) GetConstituents() []BondRef

GetConstituents returns the BondRefs for this compound's constituent protos. Returns nil for non-compound issues.

func (*Issue) IsCompound 

func (i *Issue) IsCompound() bool

IsCompound returns true if this issue is a compound (bonded from multiple sources).

func (*Issue) IsExpired 

func (i *Issue) IsExpired(ttl time.Duration) bool

IsExpired returns true if the tombstone has exceeded its TTL. Non-tombstone issues always return false. ttl is the configured TTL duration:

  • If zero, DefaultTombstoneTTL (30 days) is used
  • If negative, the tombstone is immediately expired (for --hard mode)
  • If positive, ClockSkewGrace is added only for TTLs > 1 hour

func (*Issue) IsTombstone 

func (i *Issue) IsTombstone() bool

IsTombstone returns true if the issue has been soft-deleted

func (*Issue) SetDefaults 

func (i *Issue) SetDefaults()

SetDefaults applies default values for fields omitted during JSONL import. Call this after json.Unmarshal to ensure missing fields have proper defaults:

  • Status: defaults to StatusOpen if empty
  • Priority: defaults to 2 if zero (note: P0 issues must explicitly set priority=0)
  • IssueType: defaults to TypeTask if empty

This enables smaller JSONL output by using omitempty on these fields.

func (*Issue) Validate 

func (i *Issue) Validate() error

Validate checks if the issue has valid field values (built-in statuses only)

func (*Issue) ValidateForImport 

func (i *Issue) ValidateForImport(customStatuses []string) error

ValidateForImport validates the issue for multi-repo import (federation trust model). Built-in types are validated (to catch typos). Non-built-in types are trusted since the source repo already validated them when the issue was created. This implements "trust the chain below you" from the HOP federation model.

func (*Issue) ValidateWithCustom 

func (i *Issue) ValidateWithCustom(customStatuses, customTypes []string) error

ValidateWithCustom checks if the issue has valid field values, allowing custom statuses and types in addition to built-in ones.

func (*Issue) ValidateWithCustomStatuses 

func (i *Issue) ValidateWithCustomStatuses(customStatuses []string) error

ValidateWithCustomStatuses checks if the issue has valid field values, allowing custom statuses in addition to built-in ones.

type IssueDetails 

type IssueDetails struct {
	Issue
	Labels       []string                       `json:"labels,omitempty"`
	Dependencies []*IssueWithDependencyMetadata `json:"dependencies,omitempty"`
	Dependents   []*IssueWithDependencyMetadata `json:"dependents,omitempty"`
	Comments     []*Comment                     `json:"comments,omitempty"`
	Parent       *string                        `json:"parent,omitempty"`
}

IssueDetails extends Issue with labels, dependencies, dependents, and comments. Used for JSON serialization in bd show and RPC responses.

type IssueFilter 

type IssueFilter struct {
	Status      *Status
	Priority    *int
	IssueType   *IssueType
	Assignee    *string
	Labels      []string // AND semantics: issue must have ALL these labels
	LabelsAny   []string // OR semantics: issue must have AT LEAST ONE of these labels
	TitleSearch string
	IDs         []string // Filter by specific issue IDs
	IDPrefix    string   // Filter by ID prefix (e.g., "bd-" to match "bd-abc123")
	Limit       int

	// Pattern matching
	TitleContains       string
	DescriptionContains string
	NotesContains       string

	// Date ranges
	CreatedAfter  *time.Time
	CreatedBefore *time.Time
	UpdatedAfter  *time.Time
	UpdatedBefore *time.Time
	ClosedAfter   *time.Time
	ClosedBefore  *time.Time

	// Empty/null checks
	EmptyDescription bool
	NoAssignee       bool
	NoLabels         bool

	// Numeric ranges
	PriorityMin *int
	PriorityMax *int

	// Tombstone filtering
	IncludeTombstones bool // If false (default), exclude tombstones from results

	// Ephemeral filtering
	Ephemeral *bool // Filter by ephemeral flag (nil = any, true = only ephemeral, false = only persistent)

	// Pinned filtering
	Pinned *bool // Filter by pinned flag (nil = any, true = only pinned, false = only non-pinned)

	// Template filtering
	IsTemplate *bool // Filter by template flag (nil = any, true = only templates, false = exclude templates)

	// Parent filtering: filter children by parent issue ID
	ParentID *string // Filter by parent issue (via parent-child dependency)

	// Molecule type filtering
	MolType *MolType // Filter by molecule type (nil = any, swarm/patrol/work)

	// Status exclusion (for default non-closed behavior)
	ExcludeStatus []Status // Exclude issues with these statuses

	// Type exclusion (for hiding internal types like gates)
	ExcludeTypes []IssueType // Exclude issues with these types

	// Time-based scheduling filters (GH#820)
	Deferred    bool       // Filter issues with defer_until set (any value)
	DeferAfter  *time.Time // Filter issues with defer_until > this time
	DeferBefore *time.Time // Filter issues with defer_until < this time
	DueAfter    *time.Time // Filter issues with due_at > this time
	DueBefore   *time.Time // Filter issues with due_at < this time
	Overdue     bool       // Filter issues where due_at < now AND status != closed
}

IssueFilter is used to filter issue queries

type IssueType 

type IssueType string

IssueType categorizes the kind of work 

const (
	TypeBug          IssueType = "bug"
	TypeFeature      IssueType = "feature"
	TypeTask         IssueType = "task"
	TypeEpic         IssueType = "epic"
	TypeChore        IssueType = "chore"
	TypeMessage      IssueType = "message"       // Ephemeral communication between workers
	TypeMergeRequest IssueType = "merge-request" // Merge queue entry for refinery processing
	TypeMolecule     IssueType = "molecule"      // Template molecule for issue hierarchies
	TypeGate         IssueType = "gate"          // Async coordination gate
	TypeAgent        IssueType = "agent"         // Agent identity bead
	TypeRole         IssueType = "role"          // Agent role definition
	TypeRig          IssueType = "rig"           // Rig identity bead (multi-repo workspace)
	TypeConvoy       IssueType = "convoy"        // Cross-project tracking with reactive completion
	TypeEvent        IssueType = "event"         // Operational state change record
	TypeSlot         IssueType = "slot"          // Exclusive access slot (merge-slot gate)
)

Issue type constants

func (IssueType) IsBuiltIn 

func (t IssueType) IsBuiltIn() bool

IsBuiltIn returns true if the type is a built-in type (same as IsValid). Used during multi-repo hydration to determine trust: - Built-in types: validate (catch typos) - Custom types (!IsBuiltIn): trust from source repo

func (IssueType) IsValid 

func (t IssueType) IsValid() bool

IsValid checks if the issue type value is valid

func (IssueType) IsValidWithCustom 

func (t IssueType) IsValidWithCustom(customTypes []string) bool

IsValidWithCustom checks if the issue type is valid, including custom types. Custom types are user-defined via bd config set types.custom "type1,type2,..."

func (IssueType) RequiredSections 

func (t IssueType) RequiredSections() []RequiredSection

RequiredSections returns the recommended sections for this issue type. Returns nil for types with no specific section requirements.

type IssueWithCounts 

type IssueWithCounts struct {
	*Issue
	DependencyCount int `json:"dependency_count"`
	DependentCount  int `json:"dependent_count"`
}

IssueWithCounts extends Issue with dependency relationship counts

type IssueWithDependencyMetadata 

type IssueWithDependencyMetadata struct {
	Issue
	DependencyType DependencyType `json:"dependency_type"`
}

IssueWithDependencyMetadata extends Issue with dependency relationship type Note: We explicitly include all Issue fields to ensure proper JSON marshaling

type Label 

type Label struct {
	IssueID string `json:"issue_id"`
	Label   string `json:"label"`
}

Label represents a tag on an issue

type LifecycleState 

type LifecycleState string

LifecycleState represents the state of a devlog session or branch 

const (
	StateActive    LifecycleState = "active"
	StatePaused    LifecycleState = "paused"
	StateAbandoned LifecycleState = "abandoned"
)

type MolType 

type MolType string

MolType categorizes the molecule type for swarm coordination 

const (
	MolTypeSwarm  MolType = "swarm"  // Swarm molecule: coordinated multi-polecat work
	MolTypePatrol MolType = "patrol" // Patrol molecule: recurring operational work (Witness, Deacon, etc.)
	MolTypeWork   MolType = "work"   // Work molecule: regular polecat work (default)
)

MolType constants

func (MolType) IsValid 

func (m MolType) IsValid() bool

IsValid checks if the mol type value is valid

type MoleculeProgressStats 

type MoleculeProgressStats struct {
	MoleculeID    string     `json:"molecule_id"`
	MoleculeTitle string     `json:"molecule_title"`
	Total         int        `json:"total"`           // Total steps (direct children)
	Completed     int        `json:"completed"`       // Closed steps
	InProgress    int        `json:"in_progress"`     // Steps currently in progress
	CurrentStepID string     `json:"current_step_id"` // First in_progress step ID (if any)
	FirstClosed   *time.Time `json:"first_closed,omitempty"`
	LastClosed    *time.Time `json:"last_closed,omitempty"`
}

MoleculeProgressStats provides efficient progress info for large molecules. This uses indexed queries instead of loading all steps into memory.

type RequiredSection 

type RequiredSection struct {
	Heading string // Markdown heading, e.g., "## Steps to Reproduce"
	Hint    string // Guidance for what to include
}

RequiredSection describes a recommended section for an issue type. Used by bd lint and bd create --validate for template validation.

type ScopeType 

type ScopeType string

ScopeType represents the scope of a lifecycle state change 

const (
	ScopeBranch  ScopeType = "branch"
	ScopeEntity  ScopeType = "entity"
	ScopeFile    ScopeType = "file"
	ScopeTask    ScopeType = "task"
	ScopeSession ScopeType = "session"
)

type SortPolicy 

type SortPolicy string

SortPolicy determines how ready work is ordered 

const (
	// SortPolicyHybrid prioritizes recent issues by priority, older by age
	// Recent = created within 48 hours
	// This is the default for backwards compatibility
	SortPolicyHybrid SortPolicy = "hybrid"

	// SortPolicyPriority always sorts by priority first, then creation date
	// Use for autonomous execution, CI/CD, priority-driven workflows
	SortPolicyPriority SortPolicy = "priority"

	// SortPolicyOldest always sorts by creation date (oldest first)
	// Use for backlog clearing, preventing issue starvation
	SortPolicyOldest SortPolicy = "oldest"
)

Sort policy constants

func (SortPolicy) IsValid 

func (s SortPolicy) IsValid() bool

IsValid checks if the sort policy value is valid

type StaleFilter 

type StaleFilter struct {
	Days   int    // Issues not updated in this many days
	Status string // Filter by status (open|in_progress|blocked), empty = all non-closed
	Limit  int    // Maximum issues to return
}

StaleFilter is used to filter stale issue queries

type Statistics 

type Statistics struct {
	TotalIssues             int     `json:"total_issues"`
	OpenIssues              int     `json:"open_issues"`
	InProgressIssues        int     `json:"in_progress_issues"`
	ClosedIssues            int     `json:"closed_issues"`
	BlockedIssues           int     `json:"blocked_issues"`
	DeferredIssues          int     `json:"deferred_issues"` // Issues on ice
	ReadyIssues             int     `json:"ready_issues"`
	TombstoneIssues         int     `json:"tombstone_issues"` // Soft-deleted issues
	PinnedIssues            int     `json:"pinned_issues"`    // Persistent issues
	EpicsEligibleForClosure int     `json:"epics_eligible_for_closure"`
	AverageLeadTime         float64 `json:"average_lead_time_hours"`
}

Statistics provides aggregate metrics

type Status 

type Status string

Status represents the current state of an issue 

const (
	StatusOpen       Status = "open"
	StatusInProgress Status = "in_progress"
	StatusBlocked    Status = "blocked"
	StatusDeferred   Status = "deferred" // Deliberately put on ice for later
	StatusClosed     Status = "closed"
	StatusTombstone  Status = "tombstone" // Soft-deleted issue
	StatusPinned     Status = "pinned"    // Persistent bead that stays open indefinitely
	StatusHooked     Status = "hooked"    // Work attached to an agent's hook (GUPP)
)

Issue status constants

func (Status) IsValid 

func (s Status) IsValid() bool

IsValid checks if the status value is valid (built-in statuses only)

func (Status) IsValidWithCustom 

func (s Status) IsValidWithCustom(customStatuses []string) bool

IsValidWithCustom checks if the status is valid, including custom statuses. Custom statuses are user-defined via bd config set status.custom "status1,status2,..."

type TreeNode 

type TreeNode struct {
	Issue
	Depth     int    `json:"depth"`
	ParentID  string `json:"parent_id"`
	Truncated bool   `json:"truncated"`
}

TreeNode represents a node in a dependency tree

type Validation 

type Validation struct {
	// Validator is who approved/rejected the work
	Validator *EntityRef `json:"validator"`

	// Outcome is the validation result: accepted, rejected, revision_requested
	Outcome string `json:"outcome"`

	// Timestamp is when the validation occurred
	Timestamp time.Time `json:"timestamp"`

	// Score is an optional quality score (0.0-1.0)
	Score *float32 `json:"score,omitempty"`
}

Validation records who validated/approved work completion. This is core to HOP's proof-of-stake concept - validators stake their reputation on approvals.

func (*Validation) IsValidOutcome 

func (v *Validation) IsValidOutcome() bool

IsValidOutcome checks if the outcome is a known validation outcome.

type WaitsForMeta 

type WaitsForMeta struct {
	// Gate type: "all-children" (wait for all), "any-children" (wait for first)
	Gate string `json:"gate"`
	// SpawnerID identifies which step/issue spawns the children to wait for.
	// If empty, waits for all direct children of the depends_on_id issue.
	SpawnerID string `json:"spawner_id,omitempty"`
}

WaitsForMeta holds metadata for waits-for dependencies (fanout gates). Stored as JSON in the Dependency.Metadata field.

type WorkFilter 

type WorkFilter struct {
	Status     Status
	Type       string // Filter by issue type (task, bug, feature, epic, merge-request, etc.)
	Priority   *int
	Assignee   *string
	Unassigned bool     // Filter for issues with no assignee
	Labels     []string // AND semantics: issue must have ALL these labels
	LabelsAny  []string // OR semantics: issue must have AT LEAST ONE of these labels
	Limit      int
	SortPolicy SortPolicy

	// Parent filtering: filter to descendants of a bead/epic (recursive)
	ParentID *string // Show all descendants of this issue

	// Molecule type filtering
	MolType *MolType // Filter by molecule type (nil = any, swarm/patrol/work)

	// Time-based deferral filtering (GH#820)
	IncludeDeferred bool // If true, include issues with future defer_until timestamps
}

WorkFilter is used to filter ready work queries

type WorkType 

type WorkType string

WorkType categorizes how work assignment operates for a bead (Decision 006) 

const (
	WorkTypeMutex           WorkType = "mutex"            // One worker, exclusive assignment (default)
	WorkTypeOpenCompetition WorkType = "open_competition" // Many submit, buyer picks
)

WorkType constants

func (WorkType) IsValid 

func (w WorkType) IsValid() bool

IsValid checks if the work type value is valid

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.