lesson

type AddOccurrenceOptions struct {
	LessonPath string
	// ID is optional for ordinary writes. Deterministic importers may supply a
	// UUID v4-shaped content-derived identity to make replay idempotent.
	ID         string
	Summary    string
	Context    map[string]any
	Evidence   Evidence
	Redactions []string
	Now        time.Time
}

type ChangeStatusOptions struct {
	// SpecRoot is the project root that contains the `spec/` subtree (NOT the
	// `spec/` directory itself). The Lesson is resolved at
	// SpecRoot/spec/lessons/<slug>.md.
	SpecRoot string

	// Slug is the Lesson slug. Caller is expected to have validated it via
	// lesson.ValidateSlug.
	Slug string

	// To is the canonical (title-case) target status.
	To lifecycle.Status

	// Note is the optional free-form markdown transition note, written as a
	// `## Resolution` section. REQUIRED (enforced by the cobra adapter) for
	// the Withdrawn and Superseded dispositions.
	Note string

	// Successor is the slug of the lesson that supersedes this one. REQUIRED
	// (enforced by the cobra adapter) for --to=Superseded, rejected
	// otherwise. Written as a `**Superseded By:** <slug>` header line.
	Successor string

	// PostMutation is the post-rewrite hook (typically a spec-lint pass).
	// Required; ChangeStatus returns exit 10 if nil.
	PostMutation PostMutationHook
}

type ChangeStatusResult struct {
	Slug string
	From lifecycle.Status
	To   lifecycle.Status
}

type Evidence struct {
	Kind string  `json:"kind"`
	Ref  *string `json:"ref"`
}

type FlatMigrationOptions struct {
	LessonsDir      string
	Slug            string
	Classifications []string
	Control         string
	Verification    string
	Evidence        string
	EventUUID       string
}

type FlatMigrationPreflight struct {
	Source             LegacySourceRef
	EventUUID          string
	Classifications    []string
	AlreadyMigrated    bool
	PendingTransaction bool
}

type FlatMigrationResult struct {
	CanonicalPath      string   `json:"canonical_path"`
	ManifestPath       string   `json:"manifest_path"`
	CreatedOccurrences []string `json:"created_occurrences"`
	RedactedSections   []string `json:"redacted_sections,omitempty"`
	AlreadyMigrated    bool     `json:"already_migrated"`
	PendingFinalize    bool     `json:"pending_finalize"`
}

type LegacyApplyInspection struct {
	MutationRequired bool
	Result           LegacyApplyResult
}

type LegacyApplyResult struct {
	CreatedLessons     []string               `json:"created_lessons"`
	CreatedOccurrences []string               `json:"created_occurrences"`
	StatusDecisions    []LegacyStatusDecision `json:"status_decisions"`
	Manual             []string               `json:"manual"`
	Skipped            []string               `json:"skipped"`
	Manifest           string                 `json:"manifest"`
}

type LegacyCandidate struct {
	Kind        string `json:"kind"`
	Line        int    `json:"line"`
	BytesSHA256 string `json:"bytes_sha256"`
}

type LegacyCollision struct {
	LegacyID string   `json:"legacy_id"`
	Count    int      `json:"count"`
	Keys     []string `json:"keys"`
}

type LegacyEntry struct {
	Key           string   `json:"key"`
	Kind          string   `json:"kind"`
	ParentKey     string   `json:"parent_key,omitempty"`
	LegacyID      string   `json:"legacy_id"`
	Ordinal       int      `json:"ordinal"`
	Title         string   `json:"title"`
	StartLine     int      `json:"start_line"`
	EndLine       int      `json:"end_line"`
	StartByte     int      `json:"start_byte"`
	EndByte       int      `json:"end_byte"`
	RawStatus     string   `json:"raw_status,omitempty"`
	BytesSHA256   string   `json:"bytes_sha256"`
	Raw           string   `json:"-"`
	SuggestedSlug string   `json:"suggested_slug"`
	Warnings      []string `json:"warnings,omitempty"`
}

type LegacyInventory struct {
	Source                LegacySourceRef   `json:"source"`
	LessonCount           int               `json:"lesson_count"`
	RecurrenceMarkerCount int               `json:"recurrence_marker_count"`
	EntryProjectionSHA256 string            `json:"entry_projection_sha256"`
	Collisions            []LegacyCollision `json:"collisions"`
	UnmatchedCandidates   []LegacyCandidate `json:"unmatched_candidates"`
	Warnings              []string          `json:"warnings,omitempty"`
	Entries               []LegacyEntry     `json:"entries"`
	// contains filtered or unexported fields
}

type LegacyMapping struct {
	Source  LegacySourceRef      `json:"source"`
	Entries []LegacyMappingEntry `json:"entries"`
}

type LegacyMappingEntry struct {
	Key             string   `json:"key"`
	Action          string   `json:"action"`
	Slug            string   `json:"slug,omitempty"`
	Title           string   `json:"title,omitempty"`
	Lesson          string   `json:"lesson,omitempty"`
	ProcessGap      string   `json:"process_gap,omitempty"`
	Status          string   `json:"status,omitempty"`
	Classifications []string `json:"classifications,omitempty"`
}

type LegacySourceRef struct {
	Repository  string `json:"repository"`
	Path        string `json:"path"`
	Revision    string `json:"revision"`
	CommittedAt string `json:"committed_at"`
	SHA256      string `json:"sha256"`
	ByteCount   int    `json:"byte_count"`
}

type LegacyStatusDecision struct {
	Key            string `json:"key"`
	SourceStatus   string `json:"source_status,omitempty"`
	ImportedStatus string `json:"imported_status"`
	Reason         string `json:"reason"`
}

type Lesson struct {
	Path string // absolute path on disk
	Slug string // filename without `.md`
	// Canonical is true when Path is spec/lessons/<slug>/README.md.
	Canonical bool
	// OccurrencesDir is non-empty only for canonical directory lessons.
	OccurrencesDir string

	HasLessonTitle bool   // first H1 line was `# Lesson: <title>`
	TitleLine      int    // 1-based line number of the title (0 when absent)
	Title          string // the `<title>` portion after `# Lesson: `

	Status     string // value of `**Status:**` (empty when missing)
	StatusLine int    // 1-based line of the field; 0 when absent

	Date     string // value of `**Date:**` (empty when missing)
	DateLine int    // 1-based line of the field; 0 when absent

	Owner     string // value of `**Owner:**` (empty when missing)
	OwnerLine int    // 1-based line of the field; 0 when absent

	Classifications      []string
	ClassificationsLine  int
	LegacyProvenance     string
	LegacyProvenanceLine int
	DuplicateOf          string
	DuplicateOfLine      int
	Supersedes           string
	SupersedesLine       int

	Recurred      int    // parsed `**Recurred:**` count; 0 when absent or unparsable
	RecurredRaw   string // raw value as written
	RecurredLine  int    // 1-based line of the field; 0 when absent
	RecurredValid bool   // true when RecurredRaw parsed cleanly as a non-negative integer

	SupersededBy     string // value of `**Superseded By:**` (empty when missing)
	SupersededByLine int    // 1-based line of the field; 0 when absent

	// PromotesTo is the optional `**Promotes To:** rule:<slug>` pointer a
	// Lesson gains once its durable rule has been promoted into a Rule
	// artifact — the Lesson half of the strict lesson<->rule pair, mirroring
	// the Idea's promotion pointer at its own Feature. It is optional and
	// appended after the canonical relation block, so an existing Lesson stays
	// lint-clean without it.
	PromotesTo     string
	PromotesToLine int

	Control               string
	ControlLine           int
	Verification          string
	VerificationLine      int
	Evidence              string
	EvidenceLine          int
	FrontmatterStatus     string
	FrontmatterStatusLine int
	FieldCounts           map[string]int
	SectionSequence       []string

	// SectionLines maps a present H2 section title to its 1-based heading
	// line. Only sections found in the body appear here; callers check
	// RequiredSections membership against this map's keys to find gaps.
	SectionLines map[string]int
}

type MutationError struct {
	Outcome MutationOutcome
	Err     error
}

type MutationOutcome uint8

type Occurrence struct {
	SchemaVersion int            `json:"schema_version"`
	ID            string         `json:"id"`
	OccurredAt    time.Time      `json:"occurred_at"`
	Summary       string         `json:"summary"`
	Context       map[string]any `json:"context"`
	Evidence      Evidence       `json:"evidence"`
	Redactions    []string       `json:"redactions"`
	Path          string         `json:"-"`
}

type PostMutationHook func() error

type Relation struct {
	From string `json:"from"`
	Type string `json:"type"`
	To   string `json:"to"`
}

type RelationPostMutationHook func() error

type RelationTransactionHooks struct {
	BeforeMutation func() error
	PostMutation   RelationPostMutationHook
	ReconcileNoop  bool
}

type ScaffoldOptions struct {
	Slug  string
	Title string // defaults to a title-cased slug
	Owner string // defaults to "unknown"
	Date  string // ISO-8601 (YYYY-MM-DD); defaults to today's UTC date
}