Tatara-lisp host bindings + framework intrinsics for vigy.
The host
[VigyHost] is the per-tick context handed to a vigy program.
It carries five buffers the program populates via intrinsics:
- actions — ReconcileActions emitted (
vigy-emitfamily) - desired — keyed declarative "what should be true"
- observed — keyed recorded "what currently is true"
- conditions — kubernetes-style health/readiness signals
- log — structured log lines
- trace — typed kv traces for the run's audit record
- metrics — named numeric metrics for observability
- events — kubernetes-style events for tail consumers
Plus two state surfaces the runtime manages (not the program):
- tick_start_ms — readable via
(vigy-tick) - kv — persistent k/v store, hydrated at tick start,
readable + writable via
(vigy-get/set/incr), saved back to the store at tick end
Framework verb surface
Actions (typed ReconcileKind)
(vigy-noop) — recorded; "nothing to do"
(vigy-defer reason) — "skip this tick; try next"
(vigy-pull payload) — fetch upstream state locally
(vigy-push payload) — push local state to upstream
(vigy-create payload) — target doesn't exist; create
(vigy-update payload) — target exists; modify
(vigy-delete payload) — target should not exist
(vigy-apply payload) — idempotent "make it match"
(vigy-restart payload) — runtime stuck; restart
(vigy-emit kind payload?) — escape hatch for unusual kinds
Structured state
(vigy-desired k v) — declare what should be true
(vigy-observed k v) — record what currently is true
(vigy-condition name status — kubernetes-style condition.
reason? message?) status: "true"|"false"|"unknown"
Persistent KV (survives across ticks; per-vigy scope)
(vigy-get k default?) — read; default if absent
(vigy-set k v) — write; saved on tick end
(vigy-incr k delta) — atomic numeric increment
(vigy-has? k) — presence check
(vigy-del k) — remove
Convergence / idempotency
(vigy-once k) — true exactly once per vigy lifetime
(vigy-mark-converged k) — record permanent achievement
(vigy-converged? k) — read convergence flag
Scheduling helpers
(vigy-tick) — epoch ms of this tick's start
(vigy-tick-count) — N (Nth tick of this vigy)
(vigy-since-last-tick) — ms since previous tick
(vigy-rate-limited? k min-ms) — token-bucket gate; returns true
if k was acted on within min-ms
(vigy-backoff-ms attempt) — capped exponential (2^attempt * 1000ms, max 30s)
Diagnostics
(vigy-log level msg) — text log line
(vigy-trace k v) — typed kv on the audit record
(vigy-metric name f) — numeric metric
(vigy-event kind message) — kubernetes-style event
Plus the full tatara-lisp stdlib — arithmetic, comparison, list ops, strings, channels, fibers, higher-order helpers.
Entry point
[evaluate] takes a program + a fresh host (with kv pre-loaded by
the runtime), evaluates, returns the host (now populated). The
runtime drains buffers + persists dirty kv keys.