TEST-VECTORS.md

Canonical algorithms for vectors

These test vectors are defined against a fixed, fully specified core algorithm set.

Machine-readable vectors

The executable golden vectors used by kron-core tests live in:

• core/testdata/vectors/v1.json

• core/testdata/vectors/v2.json

• core/testdata/vectors/v3.json

• core/testdata/vectors/v4.json

• core/testdata/vectors/v5.json

• core/testdata/vectors/v6.json

• core/testdata/vectors/v7.json

Current implementation coverage in that file focuses on implemented MVP behavior:

• uniform, skewEarly, and skewLate distributions (including skew shape parameter coverage)

• after, before, and around/center window behavior

• zero-duration window behavior

• seed strategies (stable, daily, weekly)

• constraint handling (hours, dow, between, dom, months, date/dates) and unschedulable outcomes

• edge cases: timezone period-key boundaries and odd around durations

Seed hash

• HASH = SHA-256

• SeedInput = Identity + "\n" + PeriodKey + "\n" + Salt

• SeedHash = hex(lowercase(SHA-256(SeedInput)))

PRNG

• PRNG = SplitMix64

• seed_u64 = uint64_be(SHA-256(SeedInput)[0:8])

• SplitMix64 step:

x = x + 0x9E3779B97F4A7C15
z = x
z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9
z = (z ^ (z >> 27)) * 0x94D049BB133111EB
z = z ^ (z >> 31)
return z

• NextFloat64():

u = next_uint64()
f = (u >> 11) / 2^53

So 0 ≤ f < 1.

Window mapping

Let W = window_end - window_start in whole seconds, where W ≥ 0.

• If W == 0: chosen_time = window_start.

• Else, for a unit value x in [0,1):

offset_seconds = floor(x * (W + 1))
chosen_time = window_start + offset_seconds seconds

This mapping permits selecting window_end when offset_seconds == W.

Distributions

Let u = NextFloat64().

• uniform:

  • x = u

• skewEarly(shape=s) where s > 0:

  • x = u^s

• skewLate(shape=s) where s > 0:

  • x = 1 - (1 - u)^s

Constraints are evaluated after mapping to a candidate time, using deterministic resampling with the same PRNG stream.

Constraint sampling budget

• MaxAttempts = 64

• Attempts consume one NextFloat64() per attempt.

If no candidate satisfies constraints after MaxAttempts, the period is unschedulable.

---

Notation

• Times are RFC3339 UTC.

• PeriodID = NominalTime.UTC().Format(RFC3339).

• For SeedStrategy=stable, PeriodKey = PeriodID.

• For SeedStrategy=daily, PeriodKey = YYYY-MM-DD in Timezone corresponding to NominalTime.

• For SeedStrategy=weekly, PeriodKey = ISO week YYYY-Www in Timezone corresponding to NominalTime.

---

Core decision vectors

V1 — uniform, after-window, stable seed

Request

• Identity: prod/db-backup

• NominalTime: 2026-03-01T00:00:00Z

• Timezone: UTC

• WindowMode: after

• WindowDuration: 3h (W=10800)

• Distribution: uniform

• SeedStrategy: stable

• Salt: backup

• Constraints: none

Expected

• PeriodID: 2026-03-01T00:00:00Z

• WindowStart: 2026-03-01T00:00:00Z

• WindowEnd: 2026-03-01T03:00:00Z

• SeedHash: 9c85657760a63b4d925af6088cceb2bb4448380b2e6856b203915a0a51ab5101

• First u: 0.8462881248863515

• offset_seconds: 9140

• ChosenTime: 2026-03-01T02:32:20Z

• Unschedulable: false

---

V2 — skewLate, around-window, stable seed

Request

• Identity: msgs/paris

• NominalTime: 2026-03-02T09:00:00Z

• Timezone: Europe/Paris

• WindowMode: around

• WindowDuration: 90m (W=5400)

• Distribution: skewLate(shape=2.5)

• SeedStrategy: stable

• Salt: msgs

• Constraints: none

Expected

• PeriodID: 2026-03-02T09:00:00Z

• WindowStart: 2026-03-02T08:15:00Z

• WindowEnd: 2026-03-02T09:45:00Z

• SeedHash: 8b95acf566414238f55eb4541a1bc726b80d02fe86a0cd2ad52988a74860b2f5

• First u: 0.4757178150383121

• x = 1 - (1-u)^2.5: 0.800972654023368

• offset_seconds: 4326

• ChosenTime: 2026-03-02T09:27:06Z

• Unschedulable: false

---

V3 — daily seed strategy

Request

• Identity: daily/test

• NominalTime: 2026-03-01T00:00:00Z

• Timezone: UTC

• WindowMode: after

• WindowDuration: 1h (W=3600)

• Distribution: uniform

• SeedStrategy: daily

• Salt: empty

• Constraints: none

Expected

• PeriodID: 2026-03-01T00:00:00Z

• PeriodKey: 2026-03-01

• WindowStart: 2026-03-01T00:00:00Z

• WindowEnd: 2026-03-01T01:00:00Z

• SeedHash: 3a1cbafc74e05e46dc6a4eff53a9d71da286eda9585a70c5c19bd43c52763161

• First u: 0.3528233669308106

• offset_seconds: 1270

• ChosenTime: 2026-03-01T00:21:10Z

• Unschedulable: false

---

V4 — zero window duration (no sampling)

Request

• Identity: exact/nojitter

• NominalTime: 2026-01-01T00:00:00Z

• Timezone: UTC

• WindowMode: after

• WindowDuration: 0s (W=0)

• Distribution: uniform

• SeedStrategy: stable

• Salt: empty

• Constraints: none

Expected

• PeriodID: 2026-01-01T00:00:00Z

• WindowStart: 2026-01-01T00:00:00Z

• WindowEnd: 2026-01-01T00:00:00Z

• SeedHash: 8b0e1ef5c9c9886e07842b8f00c04697f5257c68188a33de362a414012b4eb84

• ChosenTime: 2026-01-01T00:00:00Z

• Unschedulable: false

---

V5 — constraints cause unschedulable (sampling budget exceeded)

Constraint model

• Only: between=18:58-19:00 in UTC (inclusive bounds)

• Equivalent allowed offset range (relative to window start): 3500..3600 seconds inclusive

• MaxAttempts = 64

Request

• Identity: home/lights

• NominalTime: 2026-03-01T18:00:00Z

• Timezone: UTC

• WindowMode: after

• WindowDuration: 1h (W=3600)

• Distribution: uniform

• SeedStrategy: stable

• Salt: lights

• Constraints: Only(between=18:58-19:00)

Expected

• PeriodID: 2026-03-01T18:00:00Z

• WindowStart: 2026-03-01T18:00:00Z

• WindowEnd: 2026-03-01T19:00:00Z

• SeedHash: d61bedd4e238549ebdb9d45993ea58904aa8042c4691967c720b0f2006416345

• ChosenTime: empty

• Unschedulable: true

• Reason: no candidate accepted within MaxAttempts

---

V6 — calendar constraints (dom, months, date/dates) in zero-window cases

v6.json adds deterministic zero-window vectors to validate day/month/date-range constraint behavior.

Coverage in this vector set:

• schedulable candidate with combined Only(dom, months, dates)

• unschedulable candidate with Avoid(dom)

• unschedulable candidate with Avoid(months)

• unschedulable candidate with Avoid(dates range)

---

V7 — skew-shape parameter determinism

v7.json adds deterministic vectors for skewLate with explicit shape values.

Coverage in this vector set:

• explicit shape=1.5

• explicit shape=2.5

• stable output differences from shape changes under fixed period/window/seed strategy

---

Adapter outcome vectors

These vectors combine a core decision with policy evaluation at a specific now.

A1 — missed with deadline=0s

Decision

Use V1 decision.

• ChosenTime: 2026-03-01T02:32:20Z

Policy

• deadline = 0s

• concurrency = forbid

• suspend = false

Input

• now = 2026-03-01T02:32:21Z

• active_execution = false

• state: period not handled yet

Expected outcome

• Terminal outcome: missed

• No execution started

• Period marked handled as missed

---

A2 — executed within deadline

Decision

Use V1 decision.

• ChosenTime: 2026-03-01T02:32:20Z

Policy

• deadline = 10m

• concurrency = forbid

• suspend = false

Input

• now = 2026-03-01T02:40:00Z

• active_execution = false

• state: period not handled yet

Expected outcome

• Terminal outcome: executed

• Execution started once

• Period marked handled as executed

---

A3 — skipped due to forbid concurrency

Decision

Use V3 decision.

• ChosenTime: 2026-03-01T00:21:10Z

Policy

• deadline = 30m

• concurrency = forbid

• suspend = false

Input

• now = 2026-03-01T00:25:00Z

• active_execution = true

Expected outcome

• Terminal outcome: skipped

• No new execution started

• Period marked handled as skipped

---

A4 — idempotency prevents duplicate execution

Decision

Use V1 decision.

Policy

• deadline = 10m

• concurrency = allow

• suspend = false

Input

• now = 2026-03-01T02:35:00Z

• active_execution = false

• state: LastHandledPeriodID == 2026-03-01T00:00:00Z with outcome=executed

Expected outcome

• No execution started

• Period remains handled

• Adapter reports job_exists / already handled behavior