/**
 * Schedule Types — core JSDoc type definitions for the SF schedule module.
 *
 * Purpose: provide a single source of truth for schedule entry shapes so that
 * the store, queries, and CLI commands all agree on the data contract.
 *
 * Consumer: schedule-store.js, schedule CLI commands (S02), and UI overlays.
 */

// ─── Enums ──────────────────────────────────────────────────────────────────

/**
 * @typedef {("project"|"global")} ScheduleScope
 *   project — entries stored in `<basePath>/.sf/sf.db` (`schedule_entries`)
 *   global  — entries stored in `~/.sf/sf.db` (`schedule_entries`)
 */

/**
 * @typedef {("pending"|"done"|"cancelled"|"snoozed")} ScheduleStatus
 */

/**
 * @typedef {("reminder"|"milestone_check"|"review_due"|"recurring"|"review"|"audit"|"prompt"|"command")} ScheduleKind
 *   "review" / "audit" — surfaced to next planning turn (SF schedule system kinds).
 *   "review_due" — legacy internal name for review (backward compat).
 *   "reminder" — general reminder.
 *   "milestone_check" — milestone health check.
 *   "recurring" — cron-based recurring entry.
 *   "prompt" — autonomous prompt to dispatch when due and autonomous_dispatch=true.
 *   "command" — repo command to execute when due and autonomous_dispatch=true.
 */

/**
 * @typedef {("agent"|"user"|"system")} ScheduleCreatedBy
 */

// ─── Payloads (discriminated union by kind) ─────────────────────────────────

/**
 * @typedef {object} ReminderPayload
 * @property {string} [message]     Human-readable reminder text
 * @property {string} [unitId]      Associated unit (e.g. "M001/S01/T01")
 * @property {string} [milestoneId] Associated milestone
 */

/**
 * @typedef {object} MilestoneCheckPayload
 * @property {string} milestoneId   Milestone to check
 * @property {string} [checkType]   "validation" | "completion" | "scope-creep"
 */

/**
 * @typedef {object} ReviewDuePayload
 * @property {string} [prUrl]       Link to PR requiring review
 * @property {string} [reviewer]    Expected reviewer handle
 * @property {string} [unitId]      Unit that produced the artifact
 */

/**
 * @typedef {object} RecurringPayload
 * @property {string} cron          Cron expression (e.g. "0 9 * * 1")
 * @property {string} [unitId]      Unit to re-schedule on each tick
 * @property {string} [milestoneId] Milestone to associate with
 */

/**
 * @typedef {object} PromptPayload
 * @property {string} [prompt]      Autonomous prompt to dispatch
 * @property {string} [message]     Human-readable prompt summary
 */

/**
 * @typedef {object} CommandPayload
 * @property {string} command       Shell command to execute from the project root
 * @property {"stdout"} [capture]   Capture bounded stdout into the schedule log
 * @property {string} [result_note] Last execution result
 * @property {string} [stdout]      Bounded captured stdout when capture="stdout"
 */

/**
 * @typedef {ReminderPayload|MilestoneCheckPayload|ReviewDuePayload|RecurringPayload|PromptPayload|CommandPayload} SchedulePayload
 */

/**
 * @typedef {object} ScheduleSpec
 * @property {string}            [in]          Duration string (e.g. "2w", "1d") — fires at milestone creation
 * @property {{in: string}}      [on_complete] Duration after milestone completion
 * @property {ScheduleKind}      kind          Entry kind
 * @property {string}            title         Entry title / reminder message
 * @property {Record<string, unknown>} [payload] Extra kind-specific data
 */

// ─── Entry ──────────────────────────────────────────────────────────────────

/**
 * @typedef {object} ScheduleEntry
 * @property {number}            [schemaVersion] Schema contract version for persisted JSONL rows
 * @property {string}            id            ULID — monotonic, sortable, 28 chars
 * @property {ScheduleKind}      kind          What kind of scheduled item this is
 * @property {ScheduleStatus}    status        Current lifecycle status
 * @property {string}            due_at        ISO-8601 timestamp
 * @property {string}            created_at    ISO-8601 timestamp
 * @property {SchedulePayload}   payload       Kind-specific data
 * @property {ScheduleCreatedBy} created_by    Who created the entry
 * @property {boolean}           [autonomous_dispatch]  If true and kind is 'prompt' or 'command', autonomous mode consumes the project entry when due. Defaults false.
 * @property {string}            [snoozed_at]     ISO-8601 timestamp; set when the entry was last snoozed
 */

// ─── Guards ─────────────────────────────────────────────────────────────────

/** @type {Set<string>} */
export const VALID_KINDS = new Set([
	"reminder",
	"milestone_check",
	"review_due",
	"recurring",
	"review",
	"audit",
	"prompt",
	"command",
]);

/**
 * All valid schedule kinds — single source of truth for tooling and validation.
 * Update VALID_KINDS and ScheduleKind typedef together.
 *
 * @type {string[]}
 */
export const ALL_SCHEDULE_KINDS = [...VALID_KINDS];

/**
 * Validate that a string is a known schedule kind.
 *
 * Purpose: prevent corrupt or future-kind entries from polluting the store
 * when reading untrusted JSONL lines.
 *
 * Consumer: schedule-store.js readEntries() filter, CLI input validation.
 *
 * @param {unknown} value
 * @returns {value is ScheduleKind}
 */
export function isValidKind(value) {
	return typeof value === "string" && VALID_KINDS.has(value);
}
