diff --git a/config.example.toml b/config.example.toml index 4e276270f..a278cc71f 100644 --- a/config.example.toml +++ b/config.example.toml @@ -333,6 +333,42 @@ gate_max_failures = 5 # rate_per_second = 1.0 # per-remote-address token bucket # rate_burst = 5 +# The cron/scheduling ticker engine: how often scheduled jobs are checked, +# how many may run at once, and how long one may run. The engine polls a job +# store for what is due and dispatches each due job to the delivery it names +# -- so nothing here schedules anything by itself, it only tunes the timing. +# Absent is valid: every field defaults independently, and a section naming +# only one of them still gets the defaults for the other two. +# +# Zero (or absent) takes the default named below. A NEGATIVE value is a +# startup error, not a clamp: running something other than what was written +# is how a misconfiguration stays invisible. Zero cannot mean "off" here for +# the same reason it cannot in [tools.tool_policy] -- it is indistinguishable +# from an unset key. +# [scheduling] +# interval = "60s" # tick cadence: how often due jobs are checked. +# # Absent/zero means 1m. The finest granularity a +# # cron-style schedule needs, and polling a local +# # job store that often costs nothing. +# max_parallel = 4 # caps simultaneous parallel-pool runs, so a store +# # reporting many jobs due at once (the first tick +# # after long downtime, typically) cannot launch an +# # unbounded fan-out. Absent/zero means 4. It does +# # not bound the sequential pool, which is one by +# # definition. +# job_timeout = "1h" # bounds one run. Absent/zero means 1h. A job that +# # has not finished in an hour is stuck, and leaving +# # it in flight would suppress every later run of the +# # same job forever. +# events_sink = "none" # "bus" publishes each run and failure on the event +# # stream, which is what the dashboard timeline reads; +# # "none" (the default, same as leaving it unset) +# # leaves the engine unobservable -- a scheduled run +# # has no task or chat turn behind it, so with no +# # sink nothing anywhere records that it fired. +# # Any other value is a startup error, so a typo +# # cannot silently turn observability off. + # Playbook-binding at-rest encryption: [bindings].encryption_key resolves a # 32-byte high-entropy key through the secret registry (engine + key) and seals # each binding's HMAC secret in the SQLite bindings.secret column with AES-256- diff --git a/internal/config/config.go b/internal/config/config.go index 3a3a99f8c..7f0618363 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -516,6 +516,12 @@ type Config struct { Capture CaptureConfig `toml:"capture" yaml:"capture"` Bindings BindingsConfig `toml:"bindings" yaml:"bindings"` + // Scheduling configures the cron/scheduling ticker engine + // (internal/domain/scheduling). Absent is valid: every field + // defaults independently, so an empty section and no section at + // all produce the same resolved engine configuration. + Scheduling SchedulingConfig `toml:"scheduling" yaml:"scheduling"` + // Memory holds memory provider configuration (from config.memory.yaml). Memory MemoryConfig `toml:"memory" yaml:"memory"` @@ -777,6 +783,57 @@ type CaptureConfig struct { RateBurst int `toml:"rate_burst" yaml:"rate_burst"` } +// SchedulingConfig configures the cron/scheduling ticker engine +// (internal/domain/scheduling, epic +// archie-core-1786637496320-249-be6d9a20). Every field is optional and +// defaults independently, so an absent [scheduling] section is valid and +// resolves to the engine's own documented defaults. +// +// Zero and negative are therefore NOT the same thing here, the same +// distinction config.ToolPolicy and config.CaptureConfig make: zero is +// "unset, give me the default", which leaves negative as the only way an +// operator can name an unusable value deliberately. A negative value is a +// startup error -- a negative interval cannot be a tick cadence, and the +// values are rejected rather than clamped because silently running +// something other than what was written is how a misconfiguration stays +// invisible. +type SchedulingConfig struct { + // Interval is the tick cadence: how often the engine asks its job + // source what is due. Zero or absent means the engine's own + // scheduling.DefaultInterval (one minute); a configured value is + // used as-is. Negative is a startup error. + Interval Duration `toml:"interval" yaml:"interval"` + // MaxParallel caps simultaneous parallel-pool runs. Zero or absent + // means scheduling.DefaultMaxParallel. It does not bound the + // sequential pool, which is one by definition. Negative is a + // startup error. + MaxParallel int `toml:"max_parallel" yaml:"max_parallel"` + // JobTimeout bounds one run via context deadline. Zero or absent + // means scheduling.DefaultJobTimeout. Negative is a startup error. + JobTimeout Duration `toml:"job_timeout" yaml:"job_timeout"` + // EventsSink selects whether the engine's run and error events are + // published on the daemon's event stream. "bus" publishes them; + // absent resolves to "none", which leaves the engine's Events nil -- + // a configuration the engine documents as valid: it still runs, it + // is just unobservable. Any other value is a startup error, so a + // typo cannot silently disable observability. + EventsSink string `toml:"events_sink" yaml:"events_sink"` +} + +// EventsSink mode values for SchedulingConfig.EventsSink. The zero value +// (empty) resolves to EventsSinkNone; these are the explicit spellings, +// shared with validation so the two cannot drift. +const ( + // EventsSinkBus publishes the engine's run and error events on the + // daemon's in-process event bus, which is what the dashboard's + // timeline reads. + EventsSinkBus = "bus" + // EventsSinkNone disables emission. It is the documented way to say + // that without relying on an absent key, and it leaves the engine's + // Events nil -- valid, and unobservable. + EventsSinkNone = "none" +) + // BindingsConfig configures the playbook-binding store (t2db). When // EncryptionKey is unset, binding secrets are persisted as plaintext // (legacy behaviour); when set, they are AES-256-GCM encrypted at rest