Trace grammar

Trace grammar

Coordination in tinyhivemind-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 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	caps a topic once enough members argue a cited fact against it
evidence	supplies grounds without taking a position
question	asks for something the room has not established
commit	records the decision after quorum
defer	declines a topic and hands it to whoever holds it

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. Unlike refute and defer it is not rejected outright, because an objection with nothing to inhibit is inert rather than dangerous.

refute, and why it is off by default

refute is the mirror of object. Where an objection names a person — the author of one message — a refutation names a hypothesis, and once refutation_cap distinct members have argued a cited fact against a topic, that topic stops carrying however many supporters it has.

!refute #retries ^4 The retry path shipped disabled and has never fired.

It is the only marker that requires both a #topic and a ^cite. Without either it deposits nothing, so every refutation is grounded by construction and a topic can never be capped on an assertion with nothing behind it.

Nothing is deleted. A capped topic keeps its supporters, keeps its weight, and stays in the standings — only carried changes, so the transcript records that the room considered the option and a reader can audit the refutation back to the message it cites.

It exists because the live hidden-profile run found the gap: killing a hypothesis with !object costs one turn per advocate and grows with every new supporter, so a room runs out of budget before it runs out of advocates. The mechanism is the missing α(v) term of the honeybee model this library takes its cross-inhibition from — see Further reading.

refutation_cap is None by default, which means refutations are recorded and cap nothing. The benchmark scored the mechanism and it lost: seven points of accuracy on the simulated task, and more as each member's private read gets noisier, because a refutation is global where an objection is local. A member firing one on a noisy read removes an option for the whole room. The case it was built for — a hidden profile, where one member holds the fact that overturns a decoy — is not what that benchmark measures, which is why the mechanism is opt-in rather than removed.

defer, the abstention

!defer #pool The archivist measured the pool; this is not my area.

defer is the other marker that fails closed: without a #topic it deposits nothing, because a deferral that names nothing is not a deferral. It moves no support, silences nobody, and creates no standing — folding a transcript with the deferrals removed gives exactly the same standings.

What it does instead is address the directory. A live deferral zeroes its author's weight on that topic — a member saying "not mine" outranks anything the fold inferred about them — and promotes the topic as the contested one, so the next bid routes toward whoever does hold it. Its standing importance is 200, below question's 300: it is the least floor-moving thing a member can say.

It is the tremble dance rather than the waggle dance — a signal that recruits a different caste instead of more of the same one — and it is the only way a turn spent on nothing becomes a turn that deposits evidence about who should act.

defer_cap bounds the chain: at that many live deferrals the promotion stops and the room goes back to its standings. Without a cap the chain is bounded only by turn_budget. A deferral chain is a step repetition surface, and step repetition is the single most common observed multi-agent failure, so a host enabling deferral should set a cap.

Like the directory it feeds, it is off by default: defer_cap: None in EpisodePolicy::DEFAULT, and every added verb in this crate so far has lost on the benchmark.

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.