docs(adrs): draft ADR — app-owned scheduling

[tomkis]

Summary

Draft ADR proposing schedules move out of the K8s controller into the api-server, with Postgres as the substrate.

• agent-schedule ConfigMaps → schedules Postgres table (api-server owned)
• Per-schedule goroutines in the controller → single api-server replica holding a Postgres advisory lock
• kubectl exec + trigger files → HTTP POST to the agent-runtime harness port
• PVC-as-durable-inbox → schedule_fires outbox table with retry-until-acked
• Supersedes ADR-008 (scoped to the scheduled trigger path; the trigger-file mechanism stays for non-scheduled callers)

Filed as Proposed / DRAFT — opening for review of the framing and the alternatives before any code lands. The motivation, alternatives, and consequences sections are written to be the artifact discussion happens against; happy to iterate inline.

Related ADRs touched conceptually: 006 (ConfigMaps over CRDs — rationale clarified, not invalidated), 008 (superseded for scheduled path), 022 (harness API server — already accepts trigger receipt), 031 (RRULE/quiet hours — semantics unchanged, implementation moves to TS), 032 (reachability primitive — load-bearing for the new firing path).

Test plan

This PR is doc-only; nothing to test. Implementation will land as separate PRs after the ADR is accepted.

• Reviewers agree the framing in Context is accurate
• Reviewers agree the alternatives in "Alternatives Considered" are the right ones to evaluate
• Owner field (currently @tomkis) is correct, or reassigned during review
• Once accepted: rename DRAFT-app-owned-scheduling.md → NNN-app-owned-scheduling.md, move row in index, mark ADR-008 Superseded by ADR-NNN

🤖 Generated with Claude Code

[xjacka]

🛡️ Humr — Code Review

PR #347: docs(adrs): draft ADR — app-owned scheduling

Author: tomkis | Branch: docs/adr-app-owned-scheduling → main | Changes: +66 −0 (2 files)

Summary

This PR adds a draft ADR proposing to migrate agent scheduling from the K8s controller (ConfigMap-backed with a Go RRULE implementation and kubectl exec trigger delivery) to the api-server (Postgres-backed, TypeScript RRULE, HTTP POST trigger delivery via the harness port).

Findings

• 🟡 Warning: Leader-loss handling ("drop in-flight fires for restart-recovery") is identified as a harder consequence but no approach is sketched — this gap could lead to duplicate or dropped fires during leader turnover mid-outbox-retry. At least a one-paragraph recovery sketch in the Decision section should be added before implementation begins. (docs/adrs/DRAFT-app-owned-scheduling.md)
• 🟡 Warning: The trigger-delivery HTTP POST path doesn't specify authentication requirements — since the harness port becomes the spine of trigger delivery, documenting whether this endpoint requires a token (and how the api-server obtains it) would prevent the implementation from accidentally leaving an unauthenticated internal trigger endpoint. (docs/adrs/DRAFT-app-owned-scheduling.md)
• 🟢 Suggestion: The Postgres advisory lock type (blocking pg_advisory_lock vs. non-blocking pg_try_advisory_lock) is left implicit. Being explicit in the Decision section would help implementers choose the right acquisition/release behavior, especially under pod restarts. (docs/adrs/DRAFT-app-owned-scheduling.md)
• 🟢 Suggestion: The migration rollback path is described as "bounded but non-trivial" with no further detail — even a one-sentence note (e.g., "Keep ConfigMaps intact until Postgres-fired schedules prove stable for N days, then delete") would make the Consequences section more actionable. (docs/adrs/DRAFT-app-owned-scheduling.md)
• ✅ Looks good: Clear, well-enumerated problem statement covering RRULE duplication, JOIN gaps, pods/exec RBAC exposure, status plumbing complexity, and split domain ownership.
• ✅ Looks good: Decision section covers all required facets — storage, firing, trigger delivery, durability, status, controller changes, and migration path — a complete architectural specification.
• ✅ Looks good: Alternatives section is thorough and honestly evaluates trade-offs (shared RRULE package, ConfigMap-backed api-server, external queue, K8s CronJobs).
• ✅ Looks good: Removing pods/exec RBAC is a genuine security improvement, clearly motivated.
• ✅ Looks good: The supersession scope of ADR-008 ("scoped to 'controller-owned cron + exec-based delivery'") is precisely bounded, avoiding unintended over-reach.

Verdict

COMMENT — The ADR is well-structured and architecturally sound, but two gaps (leader-loss recovery story and harness authentication for trigger delivery) should be addressed before the decision is finalized.

---

Review by Humr · automated code guardian