Documentation
¶
Index ¶
Constants ¶
const MaxSlugLen = 100
MaxSlugLen is the maximum length of the slug portion of a trace ID (the part after YYYYMMDD-). NewID truncates longer slugs. AGENTS.md documents this so agents can aim for short titles rather than discovering silent truncation after the fact.
Variables ¶
var ErrInvalidFrontmatter = errors.New("invalid trace frontmatter")
ErrInvalidFrontmatter is returned by Validate when a Trace's frontmatter fails a required-field or enum check. The specific failure is wrapped underneath so callers can log it or branch on it.
var ErrInvalidTraceID = errors.New("invalid trace ID")
ErrInvalidTraceID is returned when a trace ID contains characters that could escape the cortex directory (path traversal). Only IDs matching the YYYYMMDD-slug format produced by NewID are accepted.
var ValidTypes = []Type{ TypeFact, TypeDecision, TypePreference, TypeContext, TypeSkill, TypeIntent, TypeObservation, TypeNote, TypeDivergence, }
Functions ¶
func ContentHash ¶ added in v0.5.0
ContentHash returns the SHA-256 hash of a trace body, prefixed with "sha256:" for algorithm-explicitness. Used for integrity verification and federation sync optimization.
func IsValidID ¶ added in v0.5.1
IsValidID reports whether id is a well-formed trace ID safe for use in filesystem paths. It rejects any ID containing path separators, dot segments, or characters outside the NewID slug alphabet.
func IsValidType ¶
func NewID ¶
NewID generates a trace ID from a title: YYYYMMDD-slugified-title.
If the slugified title already begins with a date prefix (either `YYYYMMDD-` or `YYYY-MM-DD-`), the leading date is stripped before today's date is prepended. This is a defensive measure: agents commonly include dates in titles to mark when an event occurred (e.g., "20260402 dadbot heartbeat check"), and without the strip the resulting ID would carry two date prefixes (`20260402-20260402-dadbot-heartbeat-check`). The strip does not validate that the digits form a real calendar date — its only job is to prevent visual prefix duplication in the final ID.
func Validate ¶ added in v0.9.0
Validate checks that a parsed Trace satisfies the required-field and enum constraints the DB can't enforce on its own. The traces table declares id/title/type/created/updated as NOT NULL, but SQLite treats empty strings as satisfying NOT NULL, so YAML-missing fields would slip through as junk rows. Validate closes that gap for ingest paths that parse files written by external tools (the filesystem watcher, primarily — Cortex.Add and CLI flows build Traces via trace.New, which always fills these fields with sensible values).
All errors wrap ErrInvalidFrontmatter so callers can use errors.Is to detect validation failures as a category.
Types ¶
type Frontmatter ¶
type Frontmatter struct {
ID string `yaml:"id"`
Title string `yaml:"title"`
Type string `yaml:"type"`
Author string `yaml:"author,omitempty"`
Tags []string `yaml:"tags,omitempty"`
DerivedFrom []string `yaml:"derived_from,omitempty"`
Origin string `yaml:"origin,omitempty"`
Created string `yaml:"created"`
Updated string `yaml:"updated"`
ContentHash string `yaml:"content_hash,omitempty"`
SourceHash string `yaml:"source_hash,omitempty"`
SourceLocked bool `yaml:"source_locked,omitempty"`
}
type Trace ¶
type Trace struct {
Frontmatter
Body string
}
Source Files