Move to using providers instead of inline time based schdules, this will solidify the provider contract as a first class API

Signed-off-by: Erick Bourgeois <erick@jeb.ca>

Author: ebourgeois

.claude/CHANGELOG.md

@@ -9,6 +9,110 @@ The format is based on the regulated environment requirements:
 
 ---
 
+## [2026-06-16 13:00] - ADR 0009: examples, time-based provider deploy manifests, and prose docs
+
+**Author:** Erick Bourgeois
+
+### Changed
+- `src/crd.rs`: `ScheduledMachineSpec.schedule` is now a **required**
+  `SpotScheduleRef` (was `Option<ScheduleSpec>`); removed `spec.spotSchedule`;
+  added top-level `spec.enabled` master switch; removed `ScheduleSpec` and the
+  `v1alpha1` `ScheduledMachine` module; added the `TimeBasedSpotSchedule` CRD
+  (spec + status) in `spotschedules.5spot.finos.org`. `is_enabled()` now reads
+  `spec.enabled`.
+- `src/providers/time_based.rs` (+tests) and `src/bin/spot_schedule_time_based.rs`:
+  NEW core/default provider controller — `is_active_at`/`next_transition`/
+  `reconcile`, mirroring `capital_markets`; publishes `status.active`.
+- `src/reconcilers/{scheduled_machine,helpers,spot_schedule_watch}.rs`: drive
+  activation solely from the single `spec.schedule` provider verdict; removed
+  `evaluate_schedule`; simplified `compose_should_be_active` (verdict + hold-last
+  -state); replaced `validate_activation_source` with `validate_schedule_ref`;
+  emergency-reclaim loop-breaker now patches `spec.enabled=false` (never the
+  shared provider object); watch reverse-index keys off `spec.schedule`.
+- `src/metrics.rs` (+tests): added `fivespot_time_based_active` /
+  `fivespot_time_based_transitions_total` + record fns.
+- `src/bin/{crdgen,crddoc}.rs`: emit the `TimeBasedSpotSchedule` CRD; single
+  `v1beta1` `ScheduledMachine` (dropped the multi-version merge + schedule/
+  spotSchedule XOR CEL); api.md regenerated.
+- `deploy/admission/validatingadmissionpolicy.yaml`: removed the inline-schedule
+  rules (cron/day/hour) and the "at least one" rule; the remaining schedule rule
+  pins `spec.schedule.apiVersion` to the provider group; `v1beta1`-only.
+- `docs/adr/0009-*.md` (+ index; amended 0006 §1/§3 and 0007);
+  `docs/architecture/calm/architecture.json` (provider model + flows; validated,
+  diagrams regenerated).
+- `examples/scheduledmachine-*.yaml`: migrated all to `5spot.finos.org/v1beta1`,
+  added `spec.enabled: true`, and replaced every inline `schedule:` / removed
+  `spotSchedule:` block with a single `spec.schedule:` provider reference. Basic
+  / weekend / tainted / bad-taint / kata / child-cluster now reference a
+  `TimeBasedSpotSchedule`; `scheduledmachine-spot-schedule.yaml` references
+  `CapitalMarketsSchedule` (`nyse-equities`) alone (no more AND-composition).
+- `examples/timebasedspotschedule.yaml`: NEW companion file defining the
+  `business-hours` / `weekend-only` (ns `default`) and `business-hours-toronto`
+  (ns `hosted-cluster-alpha`) provider objects the SM examples reference.
+- `examples/capitalmarketsschedule.yaml`, `examples/workshop/*`: updated
+  comments / shape to `spec.schedule` reference + `spec.enabled`; workshop now
+  installs the time-based provider and toggles `spec.enabled` / `tbss`.
+- `deploy/spot-schedule-providers/time-based/`: NEW provider deploy bundle
+  (serviceaccount / clusterrole / clusterrolebinding / deployment /
+  kustomization), mirroring the capital-markets bundle — least-privilege RBAC
+  (get/list/watch `timebasedspotschedules`, update/patch its `/status`),
+  hardened `Deployment` running `spot-schedule-time-based`.
+- `docs/src/**` and `docs/mkdocs.yml`: rewrote all spot-schedule prose to the
+  ADR 0009 shape (required `spec.schedule` provider ref; `TimeBasedSpotSchedule`
+  as the default first-party provider; `spec.enabled` master switch; emergency
+  reclaim sets `spec.enabled`; VAP single group-pin rule 4 / `v1beta1`-only
+  matchConstraints). Added a new `docs/src/guides/time-based-schedule.md` guide
+  and listed it in the nav.
+
+### Why
+ADR 0009 reified the former inline `ScheduledMachine.spec.schedule` window into
+the first-party `TimeBasedSpotSchedule` provider, made `spec.schedule` a required
+provider reference, dropped the SM `v1alpha1` version and the `spotSchedule`
+field, and introduced `spec.enabled`. Examples, deploy manifests, and docs had
+to match the new contract.
+
+### Impact
+- [x] Breaking change (pre-release CRD contract: `spec.schedule` is now a
+  required provider reference, `spec.spotSchedule` removed, SM `v1alpha1` dropped)
+- [x] Requires cluster rollout (new CRD + provider controller + RBAC; re-apply
+  `deploy/crds/` and the time-based provider bundle)
+- [ ] Config change only
+- [ ] Documentation only
+
+---
+
+**Author:** Erick Bourgeois
+
+### Changed
+- `docs/src/guides/create-your-own-provider.md`: NEW standalone guide — a
+  complete, copy-pasteable walkthrough building a minimal `ManualSchedule`
+  provider end to end: CRD (namespaced, `status` subresource), controller
+  (status-patch reconcile, `Ready` semantics, event-driven not polling),
+  least-privilege RBAC, deployment, referencing from a `ScheduledMachine`,
+  verification, and additive versioning. Language-agnostic.
+- `docs/mkdocs.yml`: grouped both provider guides under a **Spot Schedule
+  Providers** sub-section in Guides (CapitalMarketsSchedule + Create Your Own
+  Provider) — makes the existing capital-markets guide more discoverable.
+- `docs/src/reference/spot-schedule-contract.md`: replaced the inline
+  "implement your own" walkthrough with a pointer to the new guide (reference =
+  spec, guide = how-to); added both guides to See-also.
+- `docs/src/guides/capital-markets-schedule.md`: added a See-also section
+  cross-linking the concept, contract, and the new provider guide.
+
+### Why
+The "create your own provider" how-to was buried inside the contract *reference*
+page; operators asked for it (and the CapitalMarketsSchedule guide) as
+first-class entries under **Guides**. Splitting how-to from spec also keeps the
+reference page focused.
+
+### Impact
+- [ ] Breaking change
+- [ ] Requires cluster rollout
+- [ ] Config change only
+- [x] Documentation only
+
+---
+
 ## [2026-06-15 10:30] - Restore dropped spot-schedule metric functions (build fix)
 
 **Author:** Erick Bourgeois

deploy/admission/validatingadmissionpolicy.yaml

@@ -27,12 +27,11 @@ spec:
 
   matchConstraints:
     resourceRules:
-      # Both served versions must be validated (ADR 0007). v1beta1 is the
-      # storage/current version (adds spec.spotSchedule and an optional
-      # spec.schedule); v1alpha1 is the frozen, deprecated legacy version. A
-      # version omitted here would BYPASS every validation below.
+      # Single served/storage version since ADR 0009 (the pre-release v1alpha1
+      # ScheduledMachine was dropped). spec.schedule is a required provider
+      # reference. A version omitted here would BYPASS every validation below.
       - apiGroups: ["5spot.finos.org"]
-        apiVersions: ["v1alpha1", "v1beta1"]
+        apiVersions: ["v1beta1"]
         resources: ["scheduledmachines"]
         operations: ["CREATE", "UPDATE"]
 
@@ -121,84 +120,23 @@ spec:
         (format: <positive integer> followed by s, m, or h)
       reason: Invalid
 
-    # NOTE on the schedule rules below: `spec.schedule` is OPTIONAL since
-    # v1beta1 (ADR 0006) — a machine may instead delegate to a spotSchedule
-    # provider. Each schedule rule is therefore guarded with
-    # `!has(object.spec.schedule) || …` so a valid spotSchedule-only machine is
-    # not rejected. The "at least one of schedule/spotSchedule" invariant is
-    # enforced by rule 7a below (and by the CRD's own x-kubernetes-validations).
+    # NOTE on the schedule rule below: since ADR 0009, `spec.schedule` is a
+    # REQUIRED reference to a spot-schedule provider object (apiVersion/kind/
+    # name in the spotschedules.5spot.finos.org group) — the former inline time
+    # window moved to the TimeBasedSpotSchedule provider CRD, which carries its
+    # own day/hour/timezone schema validation. The only ScheduledMachine-side
+    # invariant left for this VAP is the provider group pin (rule 4). The
+    # "required" and structural shape are enforced by the CRD schema itself.
 
-    # ── 4. Cron XOR explicit day/hour windows ────────────────────────────────
-    # Using cron together with daysOfWeek or hoursOfDay is ambiguous.
-    # The controller silently ignores daysOfWeek/hoursOfDay when cron is set;
-    # we reject the spec at admission to prevent silent data loss.
-    - expression: |
-        !has(object.spec.schedule) ||
-        !has(object.spec.schedule.cron) ||
-        (object.spec.schedule.daysOfWeek.size() == 0 &&
-         object.spec.schedule.hoursOfDay.size() == 0)
-      message: >-
-        spec.schedule: cron is mutually exclusive with daysOfWeek and hoursOfDay —
-        set one or the other, not both
-      reason: Invalid
-
-    # ── 5. Without cron, both day and hour windows must be provided ───────────
-    - expression: |
-        !has(object.spec.schedule) ||
-        has(object.spec.schedule.cron) ||
-        (object.spec.schedule.daysOfWeek.size() > 0 &&
-         object.spec.schedule.hoursOfDay.size() > 0)
-      message: >-
-        spec.schedule: when cron is not set, both daysOfWeek and hoursOfDay must be
-        non-empty to define an active window
-      reason: Invalid
-
-    # ── 6. daysOfWeek item format ─────────────────────────────────────────────
-    # Each element must be a day name (mon…sun), an inclusive range (mon-fri),
-    # or a comma-separated combination (mon-wed,fri-sun).
-    # Trivially true for empty arrays (cron path).
-    - expression: |
-        !has(object.spec.schedule) ||
-        object.spec.schedule.daysOfWeek.all(d,
-          d.matches('^(mon|tue|wed|thu|fri|sat|sun)(-(mon|tue|wed|thu|fri|sat|sun))?(,(mon|tue|wed|thu|fri|sat|sun)(-(mon|tue|wed|thu|fri|sat|sun))?)*$'))
-      message: >-
-        spec.schedule.daysOfWeek items must be day names or ranges
-        (e.g. 'mon', 'mon-fri', 'mon-wed,fri-sun')
-      reason: Invalid
-
-    # ── 7. hoursOfDay item format ─────────────────────────────────────────────
-    # Each element must be a 1-2 digit hour, a range (9-17), or a comma-
-    # separated combination (0-9,18-23).  Numeric bounds (0-23) are enforced
-    # at runtime by the schedule evaluator.
-    # Trivially true for empty arrays (cron path).
-    - expression: |
-        !has(object.spec.schedule) ||
-        object.spec.schedule.hoursOfDay.all(h,
-          h.matches('^[0-9]{1,2}(-[0-9]{1,2})?(,[0-9]{1,2}(-[0-9]{1,2})?)*$'))
-      message: >-
-        spec.schedule.hoursOfDay items must be hours or ranges
-        (e.g. '9', '9-17', '0-9,18-23')
-      reason: Invalid
-
-    # ── 7a. At least one activation source ────────────────────────────────────
-    # A machine must declare an inline schedule, a spotSchedule provider, or
-    # both (ADR 0006). Mirrors the CRD x-kubernetes-validations and the runtime
-    # validate_activation_source() in src/reconcilers/helpers.rs.
-    - expression: "has(object.spec.schedule) || has(object.spec.spotSchedule)"
-      message: >-
-        at least one of spec.schedule or spec.spotSchedule must be set
-      reason: Invalid
-
-    # ── 7b. spotSchedule.apiVersion group pin ─────────────────────────────────
+    # ── 4. schedule.apiVersion group pin ──────────────────────────────────────
     # The provider reference group MUST be spotschedules.5spot.finos.org
-    # (ADR 0006 §2 / §6) — providers are untrusted inputs and the controller's
-    # read-only RBAC is scoped to exactly this group. Mirrors the CRD field CEL
-    # and the runtime group check.
+    # (ADR 0006 §2 / §6, ADR 0009) — providers are untrusted inputs and the
+    # controller's read-only RBAC is scoped to exactly this group. Mirrors the
+    # CRD field CEL and the runtime validate_schedule_ref() check.
     - expression: |
-        !has(object.spec.spotSchedule) ||
-        object.spec.spotSchedule.apiVersion.startsWith('spotschedules.5spot.finos.org/')
+        object.spec.schedule.apiVersion.startsWith('spotschedules.5spot.finos.org/')
       message: >-
-        spec.spotSchedule.apiVersion group must be spotschedules.5spot.finos.org
+        spec.schedule.apiVersion group must be spotschedules.5spot.finos.org
       reason: Invalid
 
     # ── 8. bootstrapSpec.apiVersion must use a namespaced API group ───────────