Files
archie/internal/infrastructure/cronstore/doc.go
T
sam 7b13751783 feat(cronstore): add job kind discriminator and bump schema to 2
Jobs need a discriminator for the delivery router to dispatch on, and
JobSpec had none. Add a top-level Kind field with values "chat" (default
when empty) and "workflow".

The empty value is load-bearing: every job written before this field
existed carries no kind and must keep delivering as a chat message, so an
empty Kind resolves to "chat" rather than being rejected.

DisallowUnknownFields means this additive change must bump schemaVersion,
so it goes 1 -> 2. A version-1 file still loads — Kind reads back empty —
which a test pins, because the alternative is that every existing cron job
stops firing on upgrade.

The store does not interpret the value: an unrecognised kind is persisted
verbatim and refused by the router, which owns the kind-to-runner mapping.
2026-09-14 09:54:41 +00:00

42 lines
1.9 KiB
Go

// Package cronstore is the file-backed job store that backs the scheduling
// ticker engine. It is infrastructure: it owns the on-disk layout, the
// cross-process lock, and the version-stamped JSON schema. It does not own
// timing semantics — those live in internal/domain/scheduling.
//
// Two surfaces:
//
// - scheduling.JobSource: Due(ctx, now) — what the engine consumes.
// - CRUD on JobSpec — what the CLI and dashboard consume.
//
// Both share the same Store value, the same lock, and the same on-disk
// file. The engine applies no schedule arithmetic of its own; whatever
// "due" means is the store's decision, including future kinds the store
// grows into.
//
// Concurrency model: every read and write acquires an OS-level flock on a
// sibling lock file, so a CLI edit and a daemon writer cannot tear the file.
// Conflict resolution is last-writer-wins: the second writer overwrites the
// first's whole document. The lock makes that serial rather than racy.
// In-process, two Store values for the same path are serialised by a
// package-level mutex keyed by lock-file path — flock is per file
// description on Linux and would not block them otherwise.
//
// File format (versioned; bump schemaVersion on ANY shape change
// including additive ones, since DisallowUnknownFields rejects them):
//
// {
// "schema_version": 2,
// "jobs": [ JobSpec, ... ]
// }
//
// Version 2 added JobSpec.Kind, the delivery discriminator. A version-1
// file still loads — Kind reads back empty, which the delivery router
// resolves to the chat default — so jobs created before the field existed
// keep firing the way they always did.
//
// JobSpec carries the engine-facing fields it always needed (ID, Pool,
// Detail) plus everything the store computes for it (NextRun, LastRun,
// Created, Updated). Merge semantics on Update mean a nil field in a Patch
// leaves the corresponding persisted field untouched.
package cronstore