dagr-producer

dagr producer — write the run, prove the run

You are the producer: the single writer of a run file that dagr view renders live. dagr is a representation kernel: you assert task truth, and it derives only defined view signals from those facts. Missing or wrong facts still produce a missing or wrong graph; there is no workflow engine to repair it.

Contract version: "dagr": 3 (v1/v2 files remain readable; write v3 for new runs).

Find your validator (before you write anything)

The check loop below is the only feedback you get, so resolve the dagr binary FIRST and stop if you can't:

1. $DAGR_BIN if set;
2. command -v dagr (on PATH);
3. the plugin/repo build: <dagr repo>/target/release/dagr — inside a herdr pane the runtime injects $HERDR_PLUGIN_ROOT, which IS the dagr repo root;
4. fallback: cargo run --manifest-path <dagr repo>/Cargo.toml -- check ….

No validator available → do not start writing run files; say so and stop. An unvalidated run file is exactly the silent wrongness this whole system exists to prevent.

The loop (non-negotiable)

write run.json.tmp → dagr check run.json.tmp --strict --json → fix → repeat until []
                                                             → THEN rename over run.json

Validate the candidate, then publish it — never the other way around. The pane renders whatever run.json holds, immediately; renaming an invalid candidate over it shows your error state to every viewer while you iterate. The safe transaction:

1. Write the complete next document to run.json.tmp (same directory — rename must be atomic, so same filesystem).
2. dagr check run.json.tmp --strict --json. Exit 0 with [] is clean; exit 1 means findings (E-codes are errors; W-codes mean representable- but-suspect — fix them unless you can say why not; --strict treats them as failures, prefer it). Exit 2 means the validator could not read the file at all — a path or tooling problem, never a document problem; stdout is empty on that path, so never treat empty output as clean. Stop, re-run the preflight, and never publish on a non-zero exit.
3. Only when clean: mv run.json.tmp run.json (atomic rename — the pane reloads on mtime and never sees a half-written or invalid file).
4. On failure: fix the temp file and re-check. The previous live file stays untouched — never leave run.json itself in an error state.