vyges-events — structured events & logging

Foundation, not a sign-off engine. vyges-events is the shared structured-event and logging contract that every Loom engine emits — and the substrate the MCP layer and cross-stage analysis consume. Like vyges-layout it’s a foundation crate, not a promoted vyges loom subcommand.

In an LLM/MCP-driven flow you need a queryable trail of what each tool did and why, so a late failure can be traced back to its early cause. vyges-events is that trail: each engine emits one structured vyges-events/1.0 event per finding, plus a completion event, on stderr, as newline-delimited JSON. The report/data on stdout is never touched.

Logs and events are one path

A plain log line is just an event with no code/objects. The same records render two ways, controlled by two environment knobs:

vyges-drc check block.gds --rules deck.rules      # report → stdout; events → stderr
#  at a terminal:   [WARN  vyges-drc DRC-WIDTH] width < min on layer 66  [layer:66]
#  when piped:      {"schema":"vyges-events/1.0",…,"code":"DRC-WIDTH","objects":["layer:66"]}

VYGES_LOG=error vyges-drc check block.gds --rules deck.rules   # only errors on stderr

The event

The full JSON Schema is self-published by the crate — dump it with vyges-events --schema.

How it flows (the causal trail)

• Engines emit events on stderr.
• The MCP layer (vyges mcp / vyges model) parses them into the loom-result envelope’s logs block (a compact summary — counts by severity, the codes seen — plus the events), and streams each line live as an MCP notifications/message while a long tool call runs, so you see progress instead of a capture-at-end blob.
• A vyges model run aggregates every step’s events into ~/.vyges/runs/<run_id>/events.jsonl — one ordered event stream across the whole multi-step flow, each event stamped with its run_id and step_index.

Because every event carries the design objects it touched, a late failure (e.g. a routing DRC error) can be linked back to the early event that caused it (e.g. a synthesis warning on the same net) — cause to effect, across stages.

For engine authors

Depend on the crate (vyges-tools/events, Apache-2.0) and emit via standard tracing macros:

#![allow(unused)]
fn main() {
tracing::warn!(code = "DRC-0142", objects = "net:data[3],macro:sram0", "spacing < min");
}

or build an Event directly. See the crate README for the tracing bridge and the sink (default: JSONL on stderr). Emission is daemonless — each engine writes locally; the orchestrator aggregates.