vigy-eval 0.1.5

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-emit family)
• 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.