learning

Documentation

Overview

Package learning is the pure domain layer for Pine learnings: parsing and serializing markdown+frontmatter files under .pine/learnings/. No file I/O.

Index

• Constants
• func BuildEdges(learnings []*Learning) (forward map[string]string, reverse map[string][]string)
• func CreatedMap(learnings []*Learning) map[string]time.Time
• func FindCycles(edges map[string]string) [][]string
• func IsCitationStale(missing []string) bool
• func IsSuperseded(rev map[string][]string, id string) bool
• func MissingCitedPaths(cites []string, exists func(rel string) bool) []string
• func SupersededBy(rev map[string][]string, created map[string]time.Time, id string) string
• func Tip(rev map[string][]string, created map[string]time.Time, id string) string
• func ValidScope(s string) bool
• func ValidSourceAgent(a string) bool
• func WouldCycle(edges map[string]string, from, to string) []string
• type ExtraField
• type Learning
  • func Parse(id string, raw []byte) *Learning
  • func (l *Learning) Serialize() []byte

Constants

const (
	ScopeGlobal    = "global"
	ScopeTicket    = "ticket"
	ScopeComponent = "component"
)

Scope values.

const (
	SourceClaudeCode = "claude-code"
	SourceCodex      = "codex"
	SourceCursor     = "cursor"
	SourceGemini     = "gemini"
	SourceManual     = "manual"
)

Source agent values.

const MaxSupersedeDepth = 64

MaxSupersedeDepth caps tip/cycle walks (same role as ticket dep path guards).

const Prefix = "LRN"

ID prefix for all learnings.

Functions

func BuildEdges

func BuildEdges(learnings []*Learning) (forward map[string]string, reverse map[string][]string)

BuildEdges indexes supersede relationships. Forward: id -> supersedes target. Reverse: target -> ids that supersede it.

func CreatedMap

func CreatedMap(learnings []*Learning) map[string]time.Time

CreatedMap builds id -> Created for tip/superseded-by tie-breaks.

func FindCycles

func FindCycles(edges map[string]string) [][]string

FindCycles returns each supersede cycle as a sorted member list.

func IsCitationStale

func IsCitationStale(missing []string) bool

IsCitationStale reports whether any cited path is missing.

func IsSuperseded

func IsSuperseded(rev map[string][]string, id string) bool

IsSuperseded reports whether any learning points at id.

func MissingCitedPaths

func MissingCitedPaths(cites []string, exists func(rel string) bool) []string

MissingCitedPaths returns the subset of cites for which exists returns false. Policy: if ANY cited path is missing, the learning is citation-stale. exists receives the repo-relative path as stored (typically slash-separated).

func SupersededBy

func SupersededBy(rev map[string][]string, created map[string]time.Time, id string) string

SupersededBy returns the direct superseder of id (newest Created, then higher ID).

func Tip

func Tip(rev map[string][]string, created map[string]time.Time, id string) string

Tip walks reverse supersede edges from id to the current tip.

func ValidScope

func ValidScope(s string) bool

ValidScope reports whether s is a known scope value.

func ValidSourceAgent

func ValidSourceAgent(a string) bool

ValidSourceAgent reports whether a is a known source_agent value.

func WouldCycle

func WouldCycle(edges map[string]string, from, to string) []string

WouldCycle reports cycle members if adding edge from → to would cycle. from is the new/updated learning id; to is the supersedes target.

Types

type ExtraField

type ExtraField struct {
	Key  string
	Node *yaml.Node
}

ExtraField is an unknown frontmatter key preserved verbatim.

type Learning

type Learning struct {
	ID          string // canonical, from filename (e.g. "LRN-001")
	Scope       string // global | ticket | component
	Tags        []string
	Ticket      string // when scope == ticket
	Component   string // when scope == component (a repo-relative path or module name)
	SourceAgent string
	Supersedes  string   // optional: ID of the learning this replaces
	Cites       []string // optional: repo-relative paths this insight depends on
	Created     time.Time
	Extra       []ExtraField
	Body        string

	// Runtime-only diagnostics, never serialized.
	FrontmatterID string
	Degraded      bool
	Warnings      []string
}

Learning is a parsed learning file. Body is the insight text after frontmatter.

func Parse

func Parse(id string, raw []byte) *Learning

Parse reads a learning file. id is the canonical identifier from the filename. Parse is lenient: it never returns an error.

func (*Learning) Serialize

func (l *Learning) Serialize() []byte

Serialize renders a learning back to bytes. Degraded learnings must not be serialized.