schedule

type Date struct {
	Year  int
	Month time.Month
	Day   int
}

type Frontmatter = map[string]interface{}

type RecurrenceKind string

type TaskDefinition struct {
	// Slug is a stable, kebab-case identifier unique across the inventory.
	// Once committed, a slug rename is a breaking change to the future Kafka
	// stream and requires a separate spec.
	Slug string

	// TitleTemplate is the title shown to the user. Supports only the
	// placeholders listed in publisher.SupportedPlaceholders (declared
	// in pkg/publisher/placeholders.go).
	TitleTemplate string

	// BodyTemplate is raw markdown. Supports the same placeholder set.
	BodyTemplate string

	// Recurrence classifies the cadence (daily/weekly/monthly/quarterly/yearly).
	Recurrence RecurrenceKind

	// Weekdays is the canonical set of weekdays a RecurrenceWeekday entry
	// fires on. Non-empty for RecurrenceWeekday (one or more days); nil/empty
	// and ignored for every other kind. Produced by the store adapter, which
	// normalizes the CR's string-or-list weekday value (long or short form)
	// to canonical time.Weekday values. The matcher (TasksForDate) fires the
	// entry on any day whose weekday is in this set; the publisher's period
	// token encodes the FIRING day's weekday (guaranteed in this set on a
	// firing day), so a list {Monday,Wednesday,Friday} yields three distinct
	// task files per ISO week, one per matching day.
	Weekdays []time.Weekday

	// Month is the calendar month a RecurrenceOnDate entry fires in
	// (time.January..time.December). Consulted only when
	// Recurrence == RecurrenceOnDate; is the zero value (time.Month(0)) and
	// ignored for every other kind. Produced by the store adapter from the
	// CR's spec.schedule.month field. Paired with Day: the matcher
	// (TasksForDate) fires the entry only when both this Month and Day equal
	// the civil date's month and day.
	Month time.Month

	// Day is the day-of-month a RecurrenceOnDate entry fires on (1-31).
	// Consulted only when Recurrence == RecurrenceOnDate; is the zero value (0)
	// and ignored for every other kind. Produced by the store adapter from
	// the CR's spec.schedule.day field. An OnDate of Month=February, Day=29
	// fires only in leap years (documented behavior, not an error).
	Day int

	// Frontmatter is operator-defined YAML frontmatter stamped onto the
	// generated vault file. Sourced from the `spec.template.frontmatter`
	// field on the Schedule CR (free-form map[string]interface{}). The
	// publisher seeds two defaults (`status: in_progress`,
	// `page_type: task`) and lets operator keys override them on
	// collision. `created_by: recurring-task-creator` is force-set as
	// provenance and cannot be overridden by configuration.
	Frontmatter Frontmatter

	// PeriodOffset shifts the period-anchored token by N periods. Default 0
	// (current period). Only meaningful for RecurrenceMonthly /
	// RecurrenceQuarterly / RecurrenceYearly — the CRD's CEL rule rejects
	// non-zero values for the date-anchored kinds (Daily / Weekly / Weekday).
	// Negative offsets name a prior period; the publisher's buildPeriodToken
	// applies the shift to the fire date before formatting the token.
	PeriodOffset int

	// AutoAbortPrior is the opt-in flag resolved from the CR's
	// spec.autoAbortPrior pointer by the store adapter (nil → false). A plain
	// bool, consistent with PeriodOffset's plain-int style — the schedule
	// layer stays pure data. The publisher mirrors this value onto every
	// materialized task's frontmatter as the `auto_abort_prior` key; the
	// downstream task-controller reads that key as its auto-abort eligibility
	// gate. Default false means a Schedule never opts into auto-abort unless
	// the operator explicitly sets spec.autoAbortPrior: true.
	AutoAbortPrior bool

	// Vault is the Obsidian vault slug the publisher stamps as TargetVault on
	// each CreateCommand — the controller's vaultName must equal this string
	// else the create is silently skipped as a vault mismatch. Sourced from
	// the CR's spec.vault by the store adapter; empty means "fall back to the
	// controller's legacy default (openclaw)" — wire-compatible with
	// pre-vault-aware producers.
	Vault string
}