retree

package
v0.3.1 Latest Latest
Warning

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

 Go to latest Published: Jun 30, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package retree provides the core data model and storage engine for research-tree, a tool for mapping scientific/research work as a directed acyclic graph (DAG).

Index

Constants

View Source 
const (
	// HotspotPendingChildWeight is the multiplier applied to pending children.
	HotspotPendingChildWeight = 5
	// HotspotInconclusiveOutcomeBonus is added when the node outcome is inconclusive.
	HotspotInconclusiveOutcomeBonus = 5
	// HotspotFormulaDescription documents the deterministic hotspot calculation.
	HotspotFormulaDescription = "hotness = pending_children*5 + age_days + inconclusive_bonus (bonus=5 when outcome=inconclusive)"
)

Variables

View Source 
var (
	// ErrNotFound is returned when a node or resource does not exist.
	ErrNotFound = errors.New("not found")
	// ErrUnsupportedSchema is returned when schema_version is not supported.
	ErrUnsupportedSchema = errors.New("unsupported schema")
	// ErrInvalidNode is returned when a node payload is invalid.
	ErrInvalidNode = errors.New("invalid node")
	// ErrInvalidStatus is returned when status is unknown.
	ErrInvalidStatus = errors.New("invalid status")
	// ErrInvalidClaimStatus is returned when claim status is unknown.
	ErrInvalidClaimStatus = errors.New("invalid claim status")
	// ErrInvalidArtifact is returned when artifact metadata is invalid.
	ErrInvalidArtifact = errors.New("invalid artifact")
	// ErrDuplicateID is returned when adding an existing node ID.
	ErrDuplicateID = errors.New("duplicate node id")
	// ErrCycleDetected is returned when an edge would introduce a cycle.
	ErrCycleDetected = errors.New("cycle detected")
	// ErrHasChildren is returned when deleting a node that still has children.
	ErrHasChildren = errors.New("node has children")
	// ErrInvalidResource is returned when a resource payload is invalid.
	ErrInvalidResource = errors.New("invalid resource")
	// ErrResourceBusy is returned when a resource cannot accept more leases.
	ErrResourceBusy = errors.New("resource busy")
	// ErrResourceDisabled is returned when a resource is disabled.
	ErrResourceDisabled = errors.New("resource disabled")
	// ErrResourceMaintenance is returned when a resource is under maintenance.
	ErrResourceMaintenance = errors.New("resource in maintenance")
)

Functions

func ApplyNodeDefaults 

func ApplyNodeDefaults(n *Node, now time.Time)

ApplyNodeDefaults mutates n by filling optional fields with deterministic defaults.

func ApplyResourceDefaults 

func ApplyResourceDefaults(r *Resource, now time.Time)

ApplyResourceDefaults fills default resource fields deterministically.

func MarshalNodeBinary 

func MarshalNodeBinary(n *Node) ([]byte, error)

MarshalNodeBinary encodes a node into the binary wire format v1. Returns the raw bytes without the file header.

func MarshalNodeJSON 

func MarshalNodeJSON(n *Node) ([]byte, error)

MarshalNodeJSON serializes a node using indented JSON for readability.

func ReadBinHeader 

func ReadBinHeader(data []byte) (uint8, error)

ReadBinHeader reads and validates the nodes.bin file header.

func ValidateArtifact 

func ValidateArtifact(a Artifact) error

ValidateArtifact validates one artifact metadata record.

func ValidateLease 

func ValidateLease(l ResourceLease) error

ValidateLease validates a resource lease payload.

func ValidateNode 

func ValidateNode(n *Node) error

ValidateNode validates a normalized node payload.

func ValidateResource 

func ValidateResource(r Resource) error

ValidateResource validates a resource inventory record.

func ValidateRunRecord 

func ValidateRunRecord(r RunRecord) error

ValidateRunRecord validates a structured run record.

func WriteBinHeader 

func WriteBinHeader(buf *bytes.Buffer)

WriteBinHeader writes the nodes.bin file header.

Types

type Artifact 

type Artifact struct {
	Mode        ArtifactMode `json:"mode" yaml:"mode"`
	Host        string       `json:"host,omitempty" yaml:"host,omitempty"`
	Path        string       `json:"path" yaml:"path"`
	Description string       `json:"description,omitempty" yaml:"desc,omitempty"`
	SizeBytes   int64        `json:"size_bytes,omitempty" yaml:"size_bytes,omitempty"`
}

Artifact is a reference to a file or dataset produced by a research node.

type ArtifactMode 

type ArtifactMode string

ArtifactMode specifies how an artifact is stored. 

const (
	ArtifactPath     ArtifactMode = "path"
	ArtifactEmbedded ArtifactMode = "embedded"
)

type BranchWarning 

type BranchWarning struct {
	ID            string
	Agent         string
	RootCauseNode NodeID
	ImpactedNode  NodeID
	Severity      string
	Message       string
	CreatedAt     time.Time
	AckedAt       *time.Time
}

BranchWarning is a persisted warning generated when an invalidated ancestor impacts active descendant work.

func FilterWarningsByNodeSet 

func FilterWarningsByNodeSet(warnings []BranchWarning, idSet map[NodeID]struct{}) []BranchWarning

FilterWarningsByNodeSet keeps warnings linked to nodes present in idSet.

type ClaimStatus 

type ClaimStatus string

ClaimStatus represents epistemic confidence and validity over time. 

const (
	ClaimProvisional ClaimStatus = "provisional"
	ClaimValidated   ClaimStatus = "validated"
	ClaimInvalidated ClaimStatus = "invalidated"
	ClaimSuperseded  ClaimStatus = "superseded"
)

type EndpointKind 

type EndpointKind string

EndpointKind states how a resource endpoint should be interpreted. 

const (
	EndpointNone EndpointKind = "none"
	EndpointIP   EndpointKind = "ip"
	EndpointDNS  EndpointKind = "dns"
)

type EvidenceCause added in v0.3.1 

type EvidenceCause string

EvidenceCause identifies the dominant reason evidence became unreliable. 

const (
	EvidenceCauseNone          EvidenceCause = ""
	EvidenceCauseBaseSnapshot  EvidenceCause = "base_snapshot"
	EvidenceCauseToolchain     EvidenceCause = "toolchain"
	EvidenceCauseExporter      EvidenceCause = "exporter"
	EvidenceCauseDataset       EvidenceCause = "dataset"
	EvidenceCausePromptSurface EvidenceCause = "prompt_surface"
	EvidenceCauseRuntimeEnv    EvidenceCause = "runtime_env"
	EvidenceCauseUnknown       EvidenceCause = "unknown"
)

type EvidenceStatus added in v0.3.1 

type EvidenceStatus string

EvidenceStatus captures whether a node's observed evidence is trustworthy. This is intentionally separate from outcome and claim status. 

const (
	EvidenceClean       EvidenceStatus = "clean"
	EvidenceSuspect     EvidenceStatus = "suspect"
	EvidencePoisoned    EvidenceStatus = "poisoned"
	EvidenceRevalidated EvidenceStatus = "revalidated"
)

type Filter 

type Filter struct {
	Status         NodeStatus     `json:"status,omitempty"`
	ClaimStatus    ClaimStatus    `json:"claim_status,omitempty"`
	EvidenceStatus EvidenceStatus `json:"evidence_status,omitempty"`
	EvidenceCause  EvidenceCause  `json:"evidence_cause,omitempty"`
	Outcome        Outcome        `json:"outcome,omitempty"`
	Tag            string         `json:"tag,omitempty"`
	TagsAll        []string       `json:"tags_all,omitempty"`
	TagsAny        []string       `json:"tags_any,omitempty"`
	Agent          string         `json:"agent,omitempty"`
	TitleContains  string         `json:"title_contains,omitempty"`
	ScopeContains  string         `json:"scope_contains,omitempty"`
	BodyContains   string         `json:"body_contains,omitempty"`
	ContinuedBy    NodeID         `json:"continued_by,omitempty"`
	SupersededBy   NodeID         `json:"superseded_by,omitempty"`
	HasArtifact    *bool          `json:"has_artifact,omitempty"`
	MilestoneClass MilestoneClass `json:"milestone_class,omitempty"`
	MilestoneKind  MilestoneKind  `json:"milestone_kind,omitempty"`
	CreatedAfter   time.Time      `json:"created_after,omitempty"`
	CreatedBefore  time.Time      `json:"created_before,omitempty"`
	SortBy         string         `json:"sort_by,omitempty"`
	Order          string         `json:"order,omitempty"`
	Offset         int            `json:"offset,omitempty"`
	Limit          int            `json:"limit,omitempty"`
}

Filter narrows ListNodes / QueryNodes results.

type Frontmatter 

type Frontmatter struct {
	SchemaVersion   SchemaVersion  `json:"schema_version" yaml:"schema_version"`
	ID              NodeID         `json:"id" yaml:"id"`
	Title           string         `json:"title" yaml:"title"`
	Status          NodeStatus     `json:"status" yaml:"status"`
	ClaimStatus     ClaimStatus    `json:"claim_status,omitempty" yaml:"claim_status,omitempty"`
	EvidenceStatus  EvidenceStatus `json:"evidence_status,omitempty" yaml:"evidence_status,omitempty"`
	EvidenceCause   EvidenceCause  `json:"evidence_cause,omitempty" yaml:"evidence_cause,omitempty"`
	EvidenceScope   string         `json:"evidence_scope,omitempty" yaml:"evidence_scope,omitempty"`
	Scope           string         `json:"scope,omitempty" yaml:"scope,omitempty"`
	ExitCriteria    string         `json:"exit_criteria,omitempty" yaml:"exit_criteria,omitempty"`
	Parents         []NodeID       `json:"parents,omitempty" yaml:"parents,omitempty"`
	ContinuedBy     []NodeID       `json:"continued_by,omitempty" yaml:"continued_by,omitempty"`
	SupersededBy    []NodeID       `json:"superseded_by,omitempty" yaml:"superseded_by,omitempty"`
	Agent           string         `json:"agent,omitempty" yaml:"agent,omitempty"`
	Tags            []string       `json:"tags,omitempty" yaml:"tags,omitempty"`
	Created         time.Time      `json:"created,omitempty" yaml:"created,omitempty"`
	Modified        time.Time      `json:"modified,omitempty" yaml:"modified,omitempty"`
	Outcome         Outcome        `json:"outcome,omitempty" yaml:"outcome,omitempty"`
	Revision        uint64         `json:"revision" yaml:"revision"`
	MilestoneClass  MilestoneClass `json:"milestone_class,omitempty" yaml:"milestone_class,omitempty"`
	MilestoneKind   MilestoneKind  `json:"milestone_kind,omitempty" yaml:"milestone_kind,omitempty"`
	MilestoneReason string         `json:"milestone_reason,omitempty" yaml:"milestone_reason,omitempty"`
	Relations       []Relation     `json:"relations,omitempty" yaml:"relations,omitempty"`
	PrimaryParent   *NodeID        `json:"primary_parent,omitempty" yaml:"primary_parent,omitempty"`
}

Frontmatter holds the structured metadata of a research node.

type GitCommit 

type GitCommit struct {
	Hash    string `json:"hash" yaml:"hash"`
	Message string `json:"message,omitempty" yaml:"message,omitempty"`
}

GitCommit references a git commit associated with the node.

type Graph 

type Graph struct {
	Nodes    map[NodeID]*Node
	Parents  map[NodeID][]NodeID // child -> parents
	Children map[NodeID][]NodeID // parent -> children
}

Graph is an in-memory DAG projection with parent and child indexes.

func NewGraph 

func NewGraph() *Graph

NewGraph builds an empty graph.

func (*Graph) AddNode 

func (g *Graph) AddNode(n *Node) error

AddNode inserts a new node after validation and DAG checks.

func (*Graph) GetAncestors 

func (g *Graph) GetAncestors(id NodeID) []NodeID

GetAncestors returns all ancestors in deterministic order.

func (*Graph) GetAtRiskDescendants 

func (g *Graph) GetAtRiskDescendants(id NodeID) []NodeID

GetAtRiskDescendants returns active descendants impacted by ancestor invalidation.

func (*Graph) GetChildren 

func (g *Graph) GetChildren(id NodeID) []NodeID

GetChildren returns sorted direct children IDs.

func (*Graph) GetDescendants 

func (g *Graph) GetDescendants(id NodeID) []NodeID

GetDescendants returns all descendants in deterministic order.

func (*Graph) GetNode 

func (g *Graph) GetNode(id NodeID) (*Node, error)

GetNode returns a deep copy of the node.

func (*Graph) GetParents 

func (g *Graph) GetParents(id NodeID) []NodeID

GetParents returns sorted direct parent IDs.

func (*Graph) GetRoots 

func (g *Graph) GetRoots() []NodeID

GetRoots returns nodes without parents.

func (*Graph) ListByAgent 

func (g *Graph) ListByAgent(agent string) []NodeID

ListByAgent lists node IDs assigned to the same agent.

func (*Graph) ListByClaimStatus 

func (g *Graph) ListByClaimStatus(status ClaimStatus) []NodeID

ListByClaimStatus lists node IDs filtered by claim status.

func (*Graph) ListByStatus 

func (g *Graph) ListByStatus(status NodeStatus) []NodeID

ListByStatus lists node IDs filtered by node status.

func (*Graph) ListByTag 

func (g *Graph) ListByTag(tag string) []NodeID

ListByTag lists node IDs containing the requested tag.

func (*Graph) RemoveNode 

func (g *Graph) RemoveNode(id NodeID, force bool) error

RemoveNode deletes a node. If force is false, nodes with children are rejected.

func (*Graph) UpdateNode 

func (g *Graph) UpdateNode(id NodeID, n *Node) error

UpdateNode replaces metadata and parent edges of an existing node.

func (*Graph) WouldCreateCycle 

func (g *Graph) WouldCreateCycle(nodeID NodeID, newParents []NodeID) bool

WouldCreateCycle reports whether assigning newParents to nodeID would create a cycle.

type HotspotSummary 

type HotspotSummary struct {
	ID                NodeID         `json:"id"`
	Title             string         `json:"title"`
	Status            NodeStatus     `json:"status"`
	Outcome           Outcome        `json:"outcome"`
	ClaimStatus       ClaimStatus    `json:"claim_status"`
	MilestoneClass    MilestoneClass `json:"milestone_class,omitempty"`
	MilestoneKind     MilestoneKind  `json:"milestone_kind,omitempty"`
	MilestoneReason   string         `json:"milestone_reason,omitempty"`
	Agent             string         `json:"agent"`
	PendingChildren   int            `json:"pending_children"`
	AgeDays           int            `json:"age_days"`
	PendingWeight     int            `json:"pending_weight"`
	InconclusiveBonus int            `json:"inconclusive_bonus"`
	Hotness           int            `json:"hotness"`
}

HotspotSummary describes one high-attention node in the status dashboard.

type LeaseMode 

type LeaseMode string

LeaseMode controls whether a resource claim is exclusive or shared. 

const (
	LeaseExclusive LeaseMode = "exclusive"
	LeaseShared    LeaseMode = "shared"
)

type MilestoneClass 

type MilestoneClass string

MilestoneClass marks frontier-significant nodes without conflating them with status/outcome. 

const (
	MilestoneNone   MilestoneClass = ""
	MilestoneGolden MilestoneClass = "golden"
)

type MilestoneKind 

type MilestoneKind string

MilestoneKind refines why a milestone matters within its lineage. 

const (
	MilestoneKindNone         MilestoneKind = ""
	MilestoneKindChampion     MilestoneKind = "champion"
	MilestoneKindBreakthrough MilestoneKind = "breakthrough"
	MilestoneKindPivot        MilestoneKind = "pivot"
)

type Node 

type Node struct {
	Frontmatter
	Commits            []GitCommit `json:"commits,omitempty" yaml:"commits,omitempty"`
	Runs               []RunRecord `json:"runs,omitempty" yaml:"runs,omitempty"`
	Artifacts          []Artifact  `json:"artifacts,omitempty" yaml:"artifacts,omitempty"`
	InvalidatedBy      []NodeID    `json:"invalidated_by,omitempty" yaml:"invalidated_by,omitempty"`
	InvalidationReason string      `json:"invalidation_reason,omitempty" yaml:"invalidation_reason,omitempty"`
	PoisonedBy         []NodeID    `json:"poisoned_by,omitempty" yaml:"poisoned_by,omitempty"`
	RevalidatedBy      []NodeID    `json:"revalidated_by,omitempty" yaml:"revalidated_by,omitempty"`
	PoisonReason       string      `json:"poison_reason,omitempty" yaml:"poison_reason,omitempty"`
	Body               string      `json:"body,omitempty" yaml:"-"`
}

Node is a unit of research: an idea, experiment, or decision point.

func CloneNode 

func CloneNode(n *Node) *Node

CloneNode returns a deep copy of n.

func UnmarshalNodeBinary 

func UnmarshalNodeBinary(b []byte) (*Node, error)

UnmarshalNodeBinary decodes a node from the binary wire format v1.

func UnmarshalNodeJSON 

func UnmarshalNodeJSON(b []byte) (*Node, error)

UnmarshalNodeJSON parses a node from JSON.

func (*Node) IsGolden 

func (n *Node) IsGolden() bool

IsGolden reports whether the node is marked as a golden milestone.

type NodeID 

type NodeID uint64

NodeID is a unique sequential identifier within a research root.

type NodeStatus 

type NodeStatus string

NodeStatus represents the activity state of a research node. 

const (
	StatusActive NodeStatus = "active"
	StatusDone   NodeStatus = "done"
	StatusPaused NodeStatus = "paused"
)

type NodeSummary 

type NodeSummary struct {
	ID              NodeID         `json:"id"`
	Title           string         `json:"title"`
	Status          NodeStatus     `json:"status"`
	Outcome         Outcome        `json:"outcome,omitempty"`
	ClaimStatus     ClaimStatus    `json:"claim_status"`
	Agent           string         `json:"agent"`
	Scope           string         `json:"scope,omitempty"`
	Tags            []string       `json:"tags,omitempty"`
	Revision        uint64         `json:"revision"`
	MilestoneClass  MilestoneClass `json:"milestone_class,omitempty"`
	MilestoneKind   MilestoneKind  `json:"milestone_kind,omitempty"`
	MilestoneReason string         `json:"milestone_reason,omitempty"`
	Parents         []NodeID       `json:"parents,omitempty"`
	Children        []NodeID       `json:"children,omitempty"`
}

NodeSummary is a lightweight view of a node for dashboard and query outputs. Full details are available via GetNode.

func SummarizeNodes 

func SummarizeNodes(nodes []*Node) []NodeSummary

SummarizeNodes converts a node list into lightweight summaries with bidirectional graph edges derived in O(n) from parent links.

type Outcome 

type Outcome string

Outcome captures the result of completed work. 

const (
	OutcomeUnset        Outcome = "unset"
	OutcomeSuccess      Outcome = "success"
	OutcomeFailure      Outcome = "failure"
	OutcomeInconclusive Outcome = "inconclusive"
)

type Relation added in v0.3.0 

type Relation struct {
	Type   RelationType `json:"type" yaml:"type"`
	Target NodeID       `json:"target" yaml:"target"`
	Note   string       `json:"note,omitempty" yaml:"note,omitempty"`
}

Relation is a typed, informational cross-edge between nodes. Unlike Parents, relations do NOT participate in DAG cycle enforcement — they are purely descriptive (comparison, inspiration, aggregation).

type RelationType added in v0.3.0 

type RelationType string

RelationType classifies a typed cross-edge between research nodes. 

const (
	RelDependsOn       RelationType = "depends_on"
	RelComparesAgainst RelationType = "compares_against"
	RelInspiredBy      RelationType = "inspired_by"
	RelAggregates      RelationType = "aggregates"
)

type Resource 

type Resource struct {
	ID           string       `json:"id" yaml:"id"`
	Label        string       `json:"label" yaml:"label"`
	Endpoint     string       `json:"endpoint,omitempty" yaml:"endpoint,omitempty"`
	EndpointKind EndpointKind `json:"endpoint_kind,omitempty" yaml:"endpoint_kind,omitempty"`
	Kind         ResourceKind `json:"kind" yaml:"kind"`
	Tags         []string     `json:"tags,omitempty" yaml:"tags,omitempty"`
	Enabled      bool         `json:"enabled" yaml:"enabled"`
	Maintenance  bool         `json:"maintenance,omitempty" yaml:"maintenance,omitempty"`
	Capacity     int          `json:"capacity,omitempty" yaml:"capacity,omitempty"`
	Spec         ResourceSpec `json:"spec,omitempty" yaml:"spec,omitempty"`
	Created      time.Time    `json:"created,omitempty" yaml:"created,omitempty"`
	Modified     time.Time    `json:"modified,omitempty" yaml:"modified,omitempty"`
}

Resource is a schedulable piece of hardware or capacity slice.

type ResourceEvent 

type ResourceEvent struct {
	ResourceID string              `json:"resource_id" yaml:"resource_id"`
	NodeID     NodeID              `json:"node_id" yaml:"node_id"`
	Action     ResourceEventAction `json:"action" yaml:"action"`
	Mode       LeaseMode           `json:"mode,omitempty" yaml:"mode,omitempty"`
	ClaimedBy  string              `json:"claimed_by,omitempty" yaml:"claimed_by,omitempty"`
	Note       string              `json:"note,omitempty" yaml:"note,omitempty"`
	Reason     string              `json:"reason,omitempty" yaml:"reason,omitempty"`
	Timestamp  time.Time           `json:"timestamp" yaml:"timestamp"`
}

ResourceEvent records historical occupancy changes for one resource.

type ResourceEventAction 

type ResourceEventAction string

ResourceEventAction captures lease lifecycle changes for auditability. 

const (
	ResourceEventClaim             ResourceEventAction = "claim"
	ResourceEventRelease           ResourceEventAction = "release"
	ResourceEventAutoReleaseDone   ResourceEventAction = "auto_release_done"
	ResourceEventAutoReleasePause  ResourceEventAction = "auto_release_paused"
	ResourceEventAutoReleaseDelete ResourceEventAction = "auto_release_delete"
)

type ResourceKind 

type ResourceKind string

ResourceKind classifies a resource for scheduling and reporting. 

const (
	ResourceMachine ResourceKind = "machine"
	ResourceGPU     ResourceKind = "gpu"
	ResourceCPUSlot ResourceKind = "cpu-slot"
	ResourceOther   ResourceKind = "other"
)

type ResourceLease 

type ResourceLease struct {
	ResourceID string    `json:"resource_id" yaml:"resource_id"`
	NodeID     NodeID    `json:"node_id" yaml:"node_id"`
	Mode       LeaseMode `json:"mode" yaml:"mode"`
	ClaimedBy  string    `json:"claimed_by,omitempty" yaml:"claimed_by,omitempty"`
	Note       string    `json:"note,omitempty" yaml:"note,omitempty"`
	ClaimedAt  time.Time `json:"claimed_at" yaml:"claimed_at"`
}

ResourceLease is an active node->resource occupancy claim.

type ResourceSpec 

type ResourceSpec struct {
	OS          string `json:"os,omitempty" yaml:"os,omitempty"`
	CPU         string `json:"cpu,omitempty" yaml:"cpu,omitempty"`
	RAMGB       int    `json:"ram_gb,omitempty" yaml:"ram_gb,omitempty"`
	GPU         string `json:"gpu,omitempty" yaml:"gpu,omitempty"`
	VRAMGB      int    `json:"vram_gb,omitempty" yaml:"vram_gb,omitempty"`
	StorageHint string `json:"storage_hint,omitempty" yaml:"storage_hint,omitempty"`
}

ResourceSpec holds stable, low-churn hardware notes for a resource.

type RunRecord 

type RunRecord struct {
	Timestamp     time.Time    `json:"timestamp" yaml:"timestamp"`
	ResourceID    string       `json:"resource_id,omitempty" yaml:"resource_id,omitempty"`
	Endpoint      string       `json:"endpoint,omitempty" yaml:"endpoint,omitempty"`
	EndpointKind  EndpointKind `json:"endpoint_kind,omitempty" yaml:"endpoint_kind,omitempty"`
	Host          string       `json:"host,omitempty" yaml:"host,omitempty"`
	Command       string       `json:"command,omitempty" yaml:"command,omitempty"`
	OutDir        string       `json:"outdir,omitempty" yaml:"outdir,omitempty"`
	Seed          string       `json:"seed,omitempty" yaml:"seed,omitempty"`
	ETA           string       `json:"eta,omitempty" yaml:"eta,omitempty"`
	Cost          string       `json:"cost,omitempty" yaml:"cost,omitempty"`
	Note          string       `json:"note,omitempty" yaml:"note,omitempty"`
	Valid         *bool        `json:"valid,omitempty" yaml:"valid,omitempty"`
	InvalidReason string       `json:"invalid_reason,omitempty" yaml:"invalid_reason,omitempty"`
}

RunRecord is a structured execution record attached to a node.

type SchemaVersion 

type SchemaVersion uint16

SchemaVersion is the on-disk schema version. 

const (
	// CurrentSchemaVersion is the schema version produced by this binary.
	CurrentSchemaVersion SchemaVersion = 1
)

type SnapshotMeta 

type SnapshotMeta struct {
	ID        string `json:"id"`
	CreatedAt string `json:"created_at"`
	Operation string `json:"operation"`
	Hash      string `json:"hash"`
}

SnapshotMeta describes a recoverable historical snapshot.

type StatusBuildOptions 

type StatusBuildOptions struct {
	Agent        string
	HotspotLimit int
	Now          time.Time
}

StatusBuildOptions controls optional status summary behavior.

type StatusSummary 

type StatusSummary struct {
	Total             int                            `json:"total"`
	Active            []NodeSummary                  `json:"active"`
	Done              []NodeSummary                  `json:"done"`
	Paused            []NodeSummary                  `json:"paused"`
	Warnings          []BranchWarning                `json:"warnings"`
	Agent             string                         `json:"agent"`
	StatusCounts      map[NodeStatus]int             `json:"status_counts"`
	ClaimStatusCounts map[ClaimStatus]int            `json:"claim_status_counts"`
	OutcomeCounts     map[Outcome]int                `json:"outcome_counts"`
	RunValidityCounts map[string]int                 `json:"run_validity_counts"`
	Matrix            map[NodeStatus]map[Outcome]int `json:"matrix"`
	HotspotFormula    string                         `json:"hotspot_formula"`
	Hotspots          []HotspotSummary               `json:"hotspots"`
}

StatusSummary is the stable dashboard contract for CLI and ABI consumers. Existing keys (total/active/done/paused/warnings/agent) are kept for compatibility.

func BuildStatusSummary 

func BuildStatusSummary(nodes []*Node, warnings []BranchWarning, opts StatusBuildOptions) StatusSummary

BuildStatusSummary computes a scalable status payload from node metadata.

type StorageFormat 

type StorageFormat string

StorageFormat selects the persistence codec. 

const (
	StorageJSON StorageFormat = "json"
	StorageBIN  StorageFormat = "bin"
)

type Store 

type Store struct {
	// contains filtered or unexported fields
}

Store is the primary interface to a research-tree root on disk. It provides CRUD for nodes, graph queries, filtering, artifact management, and tagging.

func Init 

func Init(rootPath string, format StorageFormat) (*Store, error)

Init creates a new research-root at rootPath.

func Open 

func Open(rootPath string) (*Store, error)

Open opens an existing research-root at rootPath.

func (*Store) AckBranchWarning 

func (s *Store) AckBranchWarning(warningID string) error

AckBranchWarning marks a warning as acknowledged.

func (*Store) AddArtifact 

func (s *Store) AddArtifact(id NodeID, a Artifact) error

AddArtifact registers an artifact reference on a node.

func (*Store) AddParents 

func (s *Store) AddParents(id NodeID, parents ...NodeID) error

AddParents adds one or more parent edges to a node without replacing existing parents.

func (*Store) AddTags 

func (s *Store) AddTags(id NodeID, tags ...string) error

AddTags adds one or more tags to a node.

func (*Store) ClaimResource 

func (s *Store) ClaimResource(lease ResourceLease) error

ClaimResource creates an active lease from a node to a resource.

func (*Store) CreateNode 

func (s *Store) CreateNode(n *Node) error

CreateNode assigns an ID and writes a new node to disk.

func (*Store) CreateResource 

func (s *Store) CreateResource(r Resource) error

CreateResource adds a new resource inventory record.

func (*Store) DeleteNode 

func (s *Store) DeleteNode(id NodeID, force bool) error

DeleteNode removes a node. If force is false and the node has children, it fails.

func (*Store) DeleteResource 

func (s *Store) DeleteResource(id string) error

DeleteResource removes a resource when it has no active leases.

func (*Store) EmbedArtifact 

func (s *Store) EmbedArtifact(id NodeID, localPath string, description string) error

EmbedArtifact copies a local file into the research root and registers it.

func (*Store) GetActiveAgents 

func (s *Store) GetActiveAgents() ([]string, error)

GetActiveAgents returns agents that have active nodes.

func (*Store) GetActiveNodes 

func (s *Store) GetActiveNodes() ([]*Node, error)

GetActiveNodes returns all nodes with status=active.

func (*Store) GetAncestors 

func (s *Store) GetAncestors(id NodeID) ([]NodeID, error)

GetAncestors returns all ancestors (DFS upward).

func (*Store) GetChildren 

func (s *Store) GetChildren(id NodeID) ([]NodeID, error)

GetChildren returns the direct children of a node.

func (*Store) GetDescendants 

func (s *Store) GetDescendants(id NodeID) ([]NodeID, error)

GetDescendants returns all descendants (DFS downward).

func (*Store) GetLeaves 

func (s *Store) GetLeaves() ([]NodeID, error)

GetLeaves returns nodes with no children.

func (*Store) GetNode 

func (s *Store) GetNode(id NodeID) (*Node, error)

GetNode retrieves a node by ID.

func (*Store) GetNodeHistory 

func (s *Store) GetNodeHistory(id NodeID) ([]*Node, error)

GetNodeHistory returns all previous versions of a node, ordered oldest-first. Returns nil if no history exists.

func (*Store) GetNodeResourceLeases 

func (s *Store) GetNodeResourceLeases(nodeID NodeID) ([]ResourceLease, error)

GetNodeResourceLeases returns active leases held by a node.

func (*Store) GetParents 

func (s *Store) GetParents(id NodeID) ([]NodeID, error)

GetParents returns the direct parents of a node.

func (*Store) GetResource 

func (s *Store) GetResource(id string) (*Resource, error)

GetResource returns one resource by ID.

func (*Store) GetResourceEvents 

func (s *Store) GetResourceEvents(resourceID string) ([]ResourceEvent, error)

GetResourceEvents returns historical occupancy events for one resource.

func (*Store) GetRoots 

func (s *Store) GetRoots() ([]NodeID, error)

GetRoots returns nodes with no parents.

func (*Store) InvalidateClaim 

func (s *Store) InvalidateClaim(target NodeID, refuter NodeID, reason string) error

InvalidateClaim marks a previously accepted claim as invalidated and records the refuter node and rationale.

func (*Store) ListAllRelations added in v0.3.0 

func (s *Store) ListAllRelations() ([]struct {
	From     NodeID
	Relation Relation
}, error)

ListAllRelations returns all relation edges across all nodes as (from, relation, target) triples.

func (*Store) ListBranchWarnings 

func (s *Store) ListBranchWarnings(agent string, onlyUnacked bool) ([]BranchWarning, error)

ListBranchWarnings returns warning events for an agent, optionally only pending (unacknowledged) ones.

func (*Store) ListNodes 

func (s *Store) ListNodes(f Filter) ([]NodeID, error)

ListNodes returns node IDs matching the filter.

func (*Store) ListRelations added in v0.3.0 

func (s *Store) ListRelations(id NodeID) ([]Relation, error)

ListRelations returns all relations for a given node from the relations.jsonl index.

func (*Store) ListResourceEvents 

func (s *Store) ListResourceEvents() ([]ResourceEvent, error)

ListResourceEvents returns all historical resource occupancy events.

func (*Store) ListResourceLeases 

func (s *Store) ListResourceLeases() ([]ResourceLease, error)

ListResourceLeases returns all active leases.

func (*Store) ListResources 

func (s *Store) ListResources() ([]Resource, error)

ListResources returns all known resources.

func (*Store) ListSnapshots 

func (s *Store) ListSnapshots() ([]SnapshotMeta, error)

ListSnapshots returns available historical snapshots.

func (*Store) MigrateStorageFormat 

func (s *Store) MigrateStorageFormat(target StorageFormat) error

MigrateStorageFormat migrates persistent state between json and binary codecs.

func (*Store) NextID 

func (s *Store) NextID() NodeID

NextID returns the next ID that would be assigned (without reserving it).

func (*Store) QueryNodes 

func (s *Store) QueryNodes(f Filter) ([]*Node, error)

QueryNodes returns full nodes matching the filter.

func (*Store) RegenerateEdges 

func (s *Store) RegenerateEdges() error

RegenerateEdges reconstructs the edges.jsonl index from stored nodes.

func (*Store) RegenerateRelations added in v0.3.0 

func (s *Store) RegenerateRelations() error

RegenerateRelations rebuilds the relations.jsonl index from stored node data.

func (*Store) ReleaseResource 

func (s *Store) ReleaseResource(nodeID NodeID, resourceID string) error

ReleaseResource removes one active lease.

func (*Store) RemoveArtifact 

func (s *Store) RemoveArtifact(id NodeID, matcher Artifact) error

RemoveArtifact removes artifact references matching the non-empty fields of the matcher.

func (*Store) RemoveParents 

func (s *Store) RemoveParents(id NodeID, parents ...NodeID) error

RemoveParents removes one or more parent edges from a node.

func (*Store) RemoveTags 

func (s *Store) RemoveTags(id NodeID, tags ...string) error

RemoveTags removes one or more tags from a node.

func (*Store) ResolveAgentName 

func (s *Store) ResolveAgentName(id string) string

ResolveAgentName looks up a human-readable name from agents.json.

func (*Store) RestoreSnapshot 

func (s *Store) RestoreSnapshot(snapshotID string) error

RestoreSnapshot restores a historical snapshot by id.

func (*Store) StorageFormat 

func (s *Store) StorageFormat() StorageFormat

StorageFormat returns the persistence codec currently used by the store.

func (*Store) UpdateNode 

func (s *Store) UpdateNode(n *Node) error

UpdateNode overwrites an existing node.

func (*Store) UpdateResource 

func (s *Store) UpdateResource(r Resource) error

UpdateResource updates an existing resource inventory record.

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.