Glossary and Events

Glossary and Events

Two closed vocabularies define everything the engine understands and everything a run records. Both are single-source and generated: the words come from engine/glossary.py (rendered to docs/GLOSSARY.md), the events from engine/events.py (rendered to docs/EVENTS.md). A selftest fails if either doc drifts from its source. This page mirrors both for reference; the source files are canonical.

The closed vocabulary — how agents speak to the engine

Agents don't converse with the engine in prose. Each reply carries exactly one line beginning >>WORD field=value, and the engine reads only that. Everything else is void to it.

Gateway rules

• The engine reads exactly one line starting >> per reply; zero or several such lines make the reply uninterpretable. Lines starting >>> are ignored (doctest noise).
• The word must be legal for the sender's role (case-insensitive); every required field must appear as field=value, non-empty.
• All other text is void to the engine. An uninterpretable reply routes sender → architect (translate | answer | escalate) → operator — it is never guessed at.
• >>TRANSLATED is the exception: its payload is the sender's whole glossary line, not named fields.

Build words (the pass flow)

These carry the real work of a delivery. A word is bound to one sender role, and the engine rejects it from any other role.

Word	Sender	Required fields	Meaning
>>WORKING	worker	—	mid-work heartbeat; never carries a question
>>QUESTION	worker	text=	a decision the worker needs; routed to the architect, ruling relayed back
>>DONE	worker	branch= summary=	all tasks built, tests green, committed on the branch
>>CONFIRMED	worker	evidence=	reply to the engine's DONE challenge: every acceptance criterion validated by the worker, with evidence — only this makes a DONE valid
>>MERGED	worker	branch= summary=	merge-window reply: the trunk is merged into the branch, conflicts resolved by the worker, full suite green on the merged state
>>WRAPPED	worker	branch= summary=	post-merge wrap: project docs updated where the block requires, session log written and committed, working tree clean — the arena may retire
>>APPROVED	reviewer	summary=	every task fulfilled and the tests pass
>>REJECTED	reviewer	findings=	numbered, actionable findings; relayed to the worker
>>TRANSLATED	architect	—	an uninterpretable message mapped to its legal form (payload = the sender's glossary line)
>>ANSWER	architect	text=	the architect's own ruling; relayed back to the sender
>>ESCALATE	architect	reason=	only the human operator can decide; surfaces in the terminal
>>ADVICE	aide	text= block=	AIDE's bootup advisory to the operator — counsel only, never a decision; block names a recommended next block or 'none'

The mapping of word → phase is set by engine/workflow.toml (see Concepts and Architecture): >>DONE/>>CONFIRMED close build, >>APPROVED/ >>REJECTED close review, >>MERGED closes merge, >>WRAPPED closes wrap. The architect words (>>TRANSLATED/>>ANSWER/>>ESCALATE) belong to the exception spine, not a phase.

Game words — an eval/demo vocabulary, clearly scoped

docs/GLOSSARY.md also lists a small game vocabulary sent by a player:

Word	Sender	Required fields	Meaning
>>SEND	player	to= text=	store-and-forward message; engine stamps identity + action ID, delivers on the recipient's next turn
>>SOLVE	player	answer=	one-shot solution who / where / what (pipe-separated); judged by the engine against the truth it dealt
>>PASS	player	—	do nothing this turn

These are not part of building software. They belong to an interactive eval/demo vehicle — a small turn-based game — that exercises the engine's messaging bus and turn machinery (store-and-forward delivery, identity and action-ID stamping, one-shot engine-judged answers) without needing a full build pipeline. The game shares the same closed-vocabulary machinery as the build words, which is precisely why it is a clean stress test of that machinery. If you see >>SEND / >>SOLVE / >>PASS and a player persona in the glossary, that's what they are — a demo/eval domain (domain = "game"), not a role you author work for. Everything on the delivery path uses the build words above.

The typed event log — how a run records itself

Every engine decision lands as one JSON line in runs/<run>.events.jsonl: ts (epoch seconds), t (a type below), plus the fields named at the emission site. The engine is the only writer, and an unknown type raises at emit time — the vocabulary is closed. This log is the single measurement source: the SIM harness, run stats, and any after-the-fact analysis aggregate these lines, never the prose transcript.

Type	Meaning
run_start	engine up on a project: flow, register size, todo count
bootup	an operator bootup-journey step answered (step, value)
recover	crash recovery at boot: strays killed / stale arena removed / doing row re-stamped todo
dispatch	a block leaves the register for an arena
phase	a seat enters a phase of the flow
gate	an engine gate ruled on a closing word (ok true/false)
verdict	a verdict seat's word, recorded durably
wall	an engine-detected wall routed (architect-first chain)
page	the operator was paged (the reply is the dependency)
answer	the operator answered a page
probe	liveness: overrun / probe answered / silent through it
land	a branch mechanically landed on the trunk
trunk_check	the suite re-ran ON the trunk after a landing
block_done	a block stamped done in the register
run_done	the run ended (blocks delivered this run)

Analysis starts at events.load(path) + events.tally(records) — walls, pages, gate bounces, rejections, landings, duration. The prose transcript (runs/<run>.log) stays the debugging companion; it is never the measurement source. Emission is checked both ways in selftests: every event type has a real engine call site, and every call site uses a legal type.

Keeping the docs honest

Both vocabularies are generated from their source module. Edit the source, then regenerate:

python3 engine/glossary.py --write   # regenerates docs/GLOSSARY.md
python3 engine/events.py   --write   # regenerates docs/EVENTS.md

Running either module with no argument reports whether its doc is in sync (and fails if stale); the same check runs in CI. Never hand-edit the generated docs/*.md. See Operations and Architecture.

Canonical sources: glossary.py · docs/GLOSSARY.md · events.py · docs/EVENTS.md.

See also: Concepts · Architecture · FAQ.