Trace grammar

Trace grammar

Coordination in tinyhivemind_core::hive is stigmergic in Grassé's sense: work leaves a trace in a shared medium, and the trace is the stimulus for the next piece of work. The transcript is the medium. No agent addresses another, and nothing in src/trace/ dispatches anything.

This page is the narrative. The complete grammar — the lexical rules, every qualifier, the fence-masking algorithm, a worked-examples table, and what is deliberately left out — is in the grammar reference.

One marker line

!<kind> [#topic] [>target] [^cite ...] [free text]

A marker is recognised only at the start of a line, ignoring leading whitespace, and only outside a fenced code block. Inline backticks need no masking, since a marker preceded by a backtick is by definition not line leading.

That layout is the convention rather than the rule. The qualifiers are read wherever they appear after the kind, so !support #a because ^3 cites 3. What is a rule is that a line is split on whitespace and nothing else, so punctuation is part of whatever it touches: !propose #stage. names the topic stage., which is not the topic stage, and support for the two never adds up. The kind itself is matched verbatim, so !Propose is prose.

!propose #stage Stage the rollout across three regions.
!support #stage ^1 Staging bounds the blast radius if the migration is wrong.
!object >3 The regions are not independent, so this does not bound anything.
!commit #stage

The eight parsed kinds

kind	what it does
propose	puts a new option on the floor
support	adds the author to a topic's supporter set
object	silences the advocate of the targeted message
refute	records a cited topic objection for audit; does not cap it
evidence	supplies grounds without taking a position
question	asks for something the room has not established
commit	records the decision after quorum
defer	parses an abstention; does not route another member

Note what object does. It names a message, not a topic, and it removes that message's author from the supporter set of the topic they were advocating. That is cross-inhibition, and Episode policy has the numbers on why the asymmetry is load bearing. It follows that an !object without a >target names nobody: the line parses and deposits a trace, and silences no one. An objection with nothing to inhibit is inert.

Retired markers

!refute and !defer appeared in earlier experiments. The parser still recognizes both markers for wire compatibility. Refutations remain in TopicStanding::refuted_by for audit, but no longer cap a topic. A deferral no longer changes episode attention or routes another member. Their syntax and measured behavior remain in the historical specification and delegation experiment. ADR 0027 records the retirement.

Reading

let traces = read(&transcript);

read folds a projected transcript into traces in sequence order. A message carrying no marker contributes nothing, so a transcript of ordinary conversation folds to an empty medium. Nothing is coerced into a vote for having been typed in a deliberating room.

resolve handles one body. Passing None extracts from the body. Passing Some, including an empty vector, selects from what extraction found there, which is a deliberately narrower contract than mention::resolve has. There is no host-side resolution step a supplied trace could legitimately carry, so a supplied entry can only name which extracted trace to keep, by its offset and kind. Anything else it claims (a different topic, target, citation, or text) is discarded in favour of what the body actually says, and a repeated offset is rejected rather than selecting the same trace twice.

TRACE_CAP is 16. A body depositing more keeps the first sixteen in reading order, for the same reason MENTION_CAP exists: one message must not be able to grow the fold without limit.

What real models get wrong

Running the grammar against live agent CLIs surfaced four failures the simulation could not reach, and every one of them is a host obligation rather than something the library can impose. Three of the four appear in the published taxonomy of multi-agent failures as well.

Models coin two names for one idea, so support splits across #rollout and #rollout-strategy and never adds up to a quorum. The fix is a prompt that names the options already on the floor, folded through the library's own standings, with each option's supporter count and how many it needs.

Models restate their own last line verbatim, sometimes for four consecutive turns. repetition_cap damps a restated support and cannot see this. The fix is showing a participant its own last line and asking for something that moves the room on.

Models write !commit while the room is still deliberating, which adds no supporter and can burn a whole budget recording a decision that was never reached. The fix is offering only the moves that count in the turn's phase.

Models drop the #, so the line names no topic and deposits nothing. The fix is calling out the sigils explicitly, with a right and a wrong example.

Benchmarks has the full account of those runs.