KeiSeiKit-1.0/DECISIONS.md

KeiSeiKit Architectural Decisions

ADR-style log. Each entry: context → decision → consequences. New entries at the top. Cross-link from _primitives/_rust/<crate>/README.md when a decision is crate-local.

---

2026-04-28 — Three scheduling abstractions in workspace

Context

After Hermes import (P4.2 kei-cron-scheduler) the KeiSeiKit workspace contains three scheduler-like primitives. A naive audit reads this as duplication; in practice each occupies a distinct layer of the stack and removing any one would break a downstream consumer. This ADR documents the boundary so a future reader does not consolidate them by mistake.

The three primitives

Crate	Storage	Concurrency	Owns runner?	Canonical use
kei-scheduler	rusqlite (sync, metadata-only)	sync	no	per-call queryable schedule index
kei-cron-scheduler	JSON-on-disk + fcntl advisory lock	tokio async	yes	Hermes parity (/schedule parser + cron loop)
kei-pipe cron triggers	embedded in pipe TOML	driven by pipe runtime	depends on pipe	pipeline-level cron embedded in a pipe definition

Decision

Keep all three. Do not consolidate. Each abstraction encodes a different ownership contract and a different blast radius on failure.

Rationale, primitive by primitive

kei-scheduler — synchronous metadata-only store

Synchronous rusqlite schedule store. Stores cron expression, next-run timestamp, owner, payload pointer. Does not dispatch — the caller asks "what should I run between t and t+Δ" and the caller is responsible for execution.

This separation matters because two callers want exactly that contract:

• kei-pipe queries the schedule from the pipe-runtime loop (already its own scheduler) — it must not have a competing async runner inside the store.
• cron-wrapper-agent test harness wants deterministic, blocking lookups with no background tasks. A tokio runtime would fight the harness.

A SQLite-backed metadata store is the smallest abstraction that satisfies both callers. Any tokio infrastructure inside this crate would force its contract on the harness and break determinism.

kei-cron-scheduler — async runner for Hermes parity

Async tokio-based runner. JSON-on-disk persistence (one file per job), fcntl advisory lock to keep multiple binaries from racing the same job file, owns its own loop, supports interval + standard 5-field cron. This is the surface imported from Hermes (HERMES-MIGRATION-PLAN P4.2) — the contract is "set-and-forget recurring scheduler with the runner inside the crate."

A SQLite-only store like kei-scheduler cannot satisfy this contract:

• File-per-job is the unit of fcntl locking; a single SQLite file would serialise all locks through the SQLite write mutex.
• The runner is part of the public surface — Hermes callers expect to hand the crate a job and walk away. Splitting the runner into a separate crate would re-litigate the contract on every consumer.

kei-pipe cron triggers — pipeline-level cron embedded in a pipe

Pipes (KeiSei pipeline definitions, TOML) can declare a cron trigger inline. The pipe runtime evaluates the trigger as part of the pipe's own state machine, alongside event triggers, file-watch triggers, and HTTP triggers. The cron trigger is not a separate scheduler — it is a trigger source within the pipe runtime, which is itself the scheduler.

Re-implementing this on top of kei-cron-scheduler would either (a) duplicate the pipe runtime's lifecycle into the cron crate, or (b) split a single pipe's triggers across two runtimes, which loses the atomic "trigger-fired-and-pipe-started" guarantee the pipe runtime provides.

Consequences

• Choosing the right primitive for a new caller. Decision tree:
  • Need a recurring background runner with fcntl durability and minimal blast radius if a single binary crashes? → kei-cron-scheduler.
  • Need a queryable index of "what should I run", with execution owned elsewhere? → kei-scheduler.
  • Trigger is one of many in a pipe definition, lives next to the data flow, dies with the pipe? → kei-pipe cron trigger.
• Fail-loud overlap. If you find yourself porting a feature from one to another (e.g. "let kei-scheduler also dispatch"), STOP — that is the No-Patching/No-Overlay smell from the umbrella rules. Add the feature to the right primitive instead, or write a new one.
• Audit signal. A future audit may flag "three schedulers" as a code smell. This ADR is the canonical answer; link here from any review comment that surfaces the question again.

References

• _primitives/_rust/kei-scheduler/
• _primitives/_rust/kei-cron-scheduler/
• _primitives/_rust/kei-pipe/ (cron trigger source)
• HERMES-MIGRATION-PLAN.md §P4.2 — Hermes parity import