Documentation
¶
Overview ¶
nova-work is both the thin client of the resident work session (docs/SPEC-WORK.md, "The engine and its client") and the kernel's side of the work description language (docs/SPEC-WORKLANG.md) and the job graph of docs/SPEC-JOBS.md.
The client sends ONE request line over the Unix socket --session names, newline-terminated, and prints the ONE line the session answers, byte for byte: OK, ROW, NOTE and MORE to stdout and exit 0, FAIL, RACED and REFUSED to stderr and exit 1. What cannot run at all -- no verb, no --session, no socket that answers -- is one WORK REFUSED line on stderr, exit 2, ending "run: nova-work help". The values travel as the caller spelled them and the session validates every one.
The bounded reader: `plan check` reads one plan under --max-bytes, --max-depth and --max-nodes, refuses a `#.` dispatch macro at the byte offset that owes it, refuses any input past a bound whole rather than truncated, and refuses an unknown `:kind` by field name. It then closes the plan's needs/blocks graph at load: `:needs` is the reference edge and `:blocks` its inverse, an absent need is refused naming the field and the id, and a `:needs` cycle is refused by validator rule 3 before publication. A well-formed plan prints one line; a refusal is exit 2 with one remedy line.
The job graph: typed needs and blocks edges, refused acyclic at seed by validator rule 3, and the mechanical ready set launch reads. A node is ready only when every need is terminal accepted. Every row that cannot proceed prints its exact blocker and its resolver; a card whose need is an open PR is never on a slot. This slice owns the in-process graph and the ready reading only: no Redis, no network, no launch, no lease.
Every path comes from a flag. There is no default file and no discovery: a missing flag is a refusal, never a guess. Output is one line per verb. Exit 0 ran and passed; exit 2 could not run -- a missing flag, an unreadable graph or plan, a :deps cycle, an unknown node, a refusal.
nova-work is also the work layer's event bridge. This binary's shipped verb, events, turns the cards:done stream and the gh fallback poll into the pub/sub messages the merge layer reacts to (docs/SPEC-JOBS.md, "Events, not ticks"). It makes no model call and writes no record: every message is a signal, and git stays the record.
Source Files