publisher

type FrontmatterFormatter interface {
	// Format returns the frontmatter for one published task. String
	// values in `operator` are rendered through the same placeholder
	// substitution as title/body (`{{date}}`, `{{iso-week}}`, etc.), and
	// the string entries of list values (`[]interface{}`, the shape a
	// CR/YAML list arrives as) are rendered the same way. Other
	// non-string values — ints, maps, and non-string list entries — pass
	// through unchanged. `slug` and `date` parameterize the placeholder render; `date` is
	// the Berlin civil date the task fires for (the publisher converts
	// wall-clock once at the tick boundary).
	//
	// `recurrence` drives the computed `defer_date` stamp: the earliest
	// date the task should surface. Point-shaped kinds (Daily, Weekday,
	// OnDate, Hourly) defer to the fire date itself; span-shaped kinds defer to the
	// start of their period — Monday of the firing ISO week for Weekly, 1st
	// of the firing month/quarter/year for the period-anchored kinds.
	// PeriodOffset is NOT applied (the offset=-1 review schedules fire
	// throughout the period they review, so the firing period's start is
	// the correct surface date). `defer_date` is stamped AFTER operator
	// keys are merged (an operator-supplied `defer_date` cannot override
	// the computed value) and BEFORE `auto_abort_prior`/`created_by` are
	// force-set. The value is an ISO "YYYY-MM-DD" string.
	//
	// `autoAbortPrior` is stamped onto the result as the
	// `auto_abort_prior` key, AFTER operator keys are merged (so an
	// operator-supplied `auto_abort_prior` cannot override the spec-level
	// value) and BEFORE `created_by` is force-set (so `created_by` stays
	// the last provenance key). The value is a Go bool serialized as a
	// YAML boolean true/false.
	Format(
		operator lib.TaskFrontmatter,
		slug string,
		date schedule.Date,
		autoAbortPrior bool,
		recurrence schedule.RecurrenceKind,
	) lib.TaskFrontmatter
}

type PeriodToken string

type PeriodTokenBuilder interface {
	// Build returns the period-anchored token for (def, date). An unknown
	// RecurrenceKind is a build-time data error (closed enum, no valid
	// runtime reason for a new value), so the implementation returns an
	// error rather than a sentinel string.
	Build(ctx context.Context, def schedule.TaskDefinition, date schedule.Date) (PeriodToken, error)
}

type Publisher interface {
	// Publish builds a CreateCommand for (def, date) and sends it. The
	// returned error is wrapped with the slug and ISO date in its message.
	// Same (def, date) on a second call produces a byte-identical command.
	Publish(ctx context.Context, def schedule.TaskDefinition, date schedule.Date) error
}

type Renderer interface {
	// Render returns template with every placeholder substituted by
	// its rendered value for date. The slug parameter is reserved for
	// future placeholders that depend on the slug itself; the current
	// set does not. Pure: no I/O, no time, no state — same inputs on
	// a second call produce a byte-identical result.
	Render(template, slug string, date schedule.Date) string
}

type TaskIdentifierCreator interface {
	// Create returns the (identifier, periodToken) pair for (def, date).
	// def.PeriodOffset shifts the period token for the period-anchored
	// recurrence kinds (Monthly / Quarterly / Yearly); the shift feeds
	// into the UUID5 input, so different offsets produce different
	// identifiers for the same fire date.
	Create(
		ctx context.Context,
		def schedule.TaskDefinition,
		date schedule.Date,
	) (lib.TaskIdentifier, PeriodToken, error)
}