# SPEC.md

## Scope

This document specifies Kron’s scheduling and execution semantics as a stable contract.

It applies to all Kron deployments and adapters:

* `kron-core` (engine)
* `krond` (host daemon)
* `kron-operator` (Kubernetes controller)

Where an adapter cannot enforce a behavior directly, it must preserve the observable contract.

---

## Terminology

* **Schedule**: A cron expression interpreted in a timezone.
* **Timezone**: IANA timezone used to interpret schedule and calendar constraints.
* **Nominal time**: The scheduled timestamp produced by resolving a schedule for a period.
* **Period**: The discrete scheduling opportunity anchored at one nominal time.
* **Period ID**: Canonical identifier for a period.
* **Window**: The allowed time interval in which an execution may be chosen.
* **Chosen time**: The specific timestamp selected within the window for a period.
* **Decision**: The computed record containing period, window, distribution, seed, and chosen time.
* **Constraint**: A rule restricting which timestamps are allowed.
* **Candidate**: A sampled timestamp within the window prior to constraint validation.
* **Deadline**: Maximum allowed lateness relative to chosen time to still execute.
* **Execution**: One realized run of a job (process spawn or Kubernetes `Job` creation).
* **Handled period**: A period for which Kron has reached a terminal outcome.
* **Terminal outcome**: `executed`, `skipped`, `missed`, or `unschedulable`.
* **Active execution**: An execution that has started but not completed.
* **Identity**: Stable identifier of a schedule entry.

---

## Time Model

* All internal comparisons use UTC instants.
* Input schedules and constraints are interpreted in the configured timezone.
* All persisted timestamps are stored as RFC3339 UTC.
* Kron’s decisions are defined at second-level granularity for chosen timestamps unless a platform supports higher precision; implementations may use higher precision but must not violate determinism for the same inputs.

---

## Inputs

A job definition provides:

* `identity`: stable identifier
* `schedule`: cron expression
* `timezone`: optional, default `UTC`
* `window_mode`: `after` or `around`
* `window_duration`: non-negative duration
* `distribution`: name + parameters
* `seed_strategy`: name + optional parameters
* `salt`: optional string
* `constraints`: optional `only` and/or `avoid`
* `policy`:

  * `concurrency`: `allow|forbid|replace`
  * `deadline`: duration (default `0s`)
  * `suspend`: boolean (default `false`)

Adapters also provide:

* `now`: current time instant

---

## Outputs

For each job, Kron produces:

* A `Decision` for a specific `Period`:

  * `period_id`
  * `nominal_time`
  * `window_start`
  * `window_end`
  * `chosen_time`
  * `timezone`
  * `distribution` + parameters
  * `seed_strategy` + parameters
  * `seed_hash`
  * `constraints_applied` summary
* A terminal outcome per period:

  * `executed`
  * `skipped`
  * `missed`
  * `unschedulable`

---

## Periods

### Period definition

A period is the interval of responsibility anchored at one resolved nominal time.

For a schedule `S`, timezone `TZ`, and an evaluation time `t`, define:

* `prev_nominal(t)`: greatest nominal time ≤ `t`
* `next_nominal(t)`: smallest nominal time > `t`

A period is identified by its nominal time.

### Period ID

`period_id` is the RFC3339 UTC representation of the nominal time.

Canonical form:

```
period_id = nominal_time_utc_rfc3339
```

Implementations must treat the same nominal instant as the same period even if represented in different timezones.

---

## Window Semantics

Given nominal time `N` and window duration `D`:

* If `window_mode=after`:

  * `window_start = N`
  * `window_end = N + D`
* If `window_mode=around`:

  * `window_start = N - (D / 2)`
  * `window_end = N + (D / 2)`

`window_start` and `window_end` are inclusive bounds for candidate generation, with the constraint that the chosen time must satisfy:

```
window_start ≤ chosen_time ≤ window_end
```

If `D=0`, then:

```
chosen_time = N
```

---

## Distribution Semantics

A distribution maps a seeded pseudorandom stream to a time within the window.

Distributions must be bounded: no value outside the window may be chosen.

Distributions may require parameters; missing parameters imply deterministic defaults.

Distribution evaluation must be deterministic for identical inputs.

The chosen time must be stable for:

* the same `identity`
* the same `period_id`
* the same schedule configuration
* the same seed strategy and salt

---

## Seed Semantics

### Determinism requirement

Kron must produce the same `chosen_time` for the same job definition and period, independent of:

* process restarts
* leader changes
* reconciliation frequency

### Seed inputs

Seed derivation uses:

* `identity`
* `period_key` (derived from `period_id` and seed strategy)
* `salt` (string, possibly empty)

### Seed strategies

Seed strategies define the `period_key`:

* `stable`: `period_key = period_id`
* `daily`: `period_key = YYYY-MM-DD in TZ corresponding to nominal time`
* `weekly`: `period_key = ISO week (YYYY-Www) in TZ corresponding to nominal time`

### Seed hash

Kron computes:

```
seed_hash = HASH(identity || "\n" || period_key || "\n" || salt)
```

Where:

* `HASH` is a stable algorithm selected by Kron (cryptographic hash required)
* `identity`, `period_key`, and `salt` are UTF-8 strings
* `||` indicates concatenation

`seed_hash` is the canonical seed representation exposed in logs and status.

The pseudorandom generator uses `seed_hash` as seed material in a stable, specified transformation.

---

## Constraint Semantics

Constraints restrict allowable chosen times.

* `only` defines the allowed set.
* `avoid` defines the disallowed set.
* If both are present, a time is valid only if it satisfies `only` and does not satisfy `avoid`.

Constraints are evaluated in the schedule timezone.

Constraints apply to candidate timestamps during decision computation.

### Candidate selection with constraints

To compute `chosen_time`:

1. Sample a candidate within the window using the distribution.
2. If candidate violates constraints, reject and sample a new candidate.
3. Continue until a valid candidate is found or the sampling budget is exhausted.

Sampling budget is deterministic and fixed by Kron.

### Unschedulable periods

If no valid candidate is found within the sampling budget, the period outcome is `unschedulable` and no execution occurs.

---

## Decision Computation

For each job and period:

1. Resolve `nominal_time` for the period based on schedule and timezone.
2. Compute window bounds.
3. Compute `period_key` based on seed strategy.
4. Compute `seed_hash`.
5. Initialize deterministic pseudorandom generator from `seed_hash`.
6. Sample candidate(s) according to distribution within window.
7. Apply constraints.
8. Produce `Decision` including chosen time and metadata.

A `Decision` is specific to one period.

If the job definition changes, decisions for future periods may change. Decisions for already-handled periods must not cause additional execution.

---

## Handling and Outcomes

A period is handled exactly once by reaching one terminal outcome.

Terminal outcomes:

* `executed`: an execution was started for the period
* `skipped`: execution was intentionally not started due to policy
* `missed`: execution was not started because the deadline expired
* `unschedulable`: no valid time could be selected within the window and constraints

Once a period is handled, Kron must not start another execution for that period.

---

## Execution Trigger Semantics

A period becomes eligible for trigger when:

```
now ≥ chosen_time
```

If `policy.suspend=true`, no trigger occurs and no period is handled while suspended.

When eligible, Kron attempts to reach a terminal outcome by evaluating policies and system state.

---

## Deadline Semantics

Let:

* `C` be `chosen_time`
* `DL` be `policy.deadline`
* `now` current time at trigger evaluation

If `DL=0s`, then the period is handled as `missed` if `now > C`.

If `DL>0s`, then:

* If `now ≤ C + DL`, execution may proceed
* If `now > C + DL`, the period is handled as `missed`

---

## Concurrency Semantics

Concurrency policy is evaluated at trigger time.

Let `active` indicate whether there is an active execution for the job identity.

* `allow`: proceed to execute regardless of `active`.
* `forbid`: if `active=true`, handle period as `skipped`.
* `replace`: if `active=true`, terminate the active execution and proceed to execute.

Termination semantics for `replace` are adapter-defined but must be best-effort and observable.

---

## Idempotency Semantics

Kron must guarantee at most one execution per `(identity, period_id)`.

Adapters must implement an idempotency check before starting execution.

* In Kubernetes mode: by checking for an existing owned Job with the period identifier.
* In daemon mode: by consulting persisted state and verifying active/existing executions.

If an execution for the period is already recorded as started or completed, the period is handled and must not be executed again.

---

## State Machine

Per job identity, each period transitions:

* `Planned`: decision computed, chosen time known
* `Eligible`: now ≥ chosen_time
* `Terminal`: one of `executed|skipped|missed|unschedulable`

Execution sub-states for `executed`:

* `Running`: started, not yet completed
* `Completed`: finished with an exit result (adapter-specific)

State transitions are monotonic.

A period cannot transition from a terminal outcome to a different terminal outcome.

---

## Spec Change Semantics

A job definition change is any change to:

* schedule
* timezone
* window mode/duration
* distribution or parameters
* constraints
* seed strategy or salt
* policy settings

Effects:

* Future decisions may change starting from the first unhandled period.
* Already-handled periods must remain handled and must not execute again.
* Active executions are governed by concurrency policy and adapter behavior.

---

## Clock Change Semantics

Kron treats `now` as authoritative input.

* If `now` jumps forward, some periods may become immediately eligible and will be handled subject to deadline and idempotency.
* If `now` jumps backward, Kron must not re-handle already handled periods.

Adapters must persist handled period outcomes to preserve idempotency across clock changes.

---

## Observability Contract

For each period and identity, Kron must expose:

* `period_id`
* `nominal_time`
* `chosen_time`
* terminal outcome
* reason for non-execution (`skipped`, `missed`, `unschedulable`) when applicable
* seed hash and distribution metadata sufficient to reproduce the decision

Logs must contain enough information to reproduce the decision off-line.

---

## Invariants

Kron guarantees:

1. `chosen_time` is within `[window_start, window_end]`.
2. At most one execution per `(identity, period_id)`.
3. Deterministic `chosen_time` for the same inputs and period.
4. No unbounded historical replay.
5. Terminal outcomes are monotonic and permanent for a period.
6. Suspension prevents executions without advancing handled periods.
7. If constraints make selection impossible, the period becomes `unschedulable` and no execution occurs.

---

## Compatibility

* The meaning of `period_id`, window computation, seed hashing inputs, and determinism rules are stable contracts.
* New distributions, parameters, and constraint types may be added.
* Any behavior change that affects decisions for the same inputs requires a major version bump of the relevant API surface.