tallydocs
gromit 0.2.0
Docs menu
Docs / Start here / Concepts

Concepts

What each moving part is, what it owns and how they connect. Read this first. The rest of the docs assume these words.

FOR AGENTS · THIS PAGE AS MARKDOWN: /concepts.md
  • Everyone runs a sidecar. It holds the device key, signs events, keeps the whole log and folds it.
  • Tools, adapters and agents talk only to their own person's sidecar, over a unix socket.
  • The sidecar checks every event against the contracts before sending it. A rejected event never leaves the machine.
  • The relay stores and forwards signed events. It checks membership and feed order, not contracts.
  • Every sidecar folds the same log with the same contracts, so everyone sees the same state.
  • Contracts are YAML in the governance repo. Every contract file in the active commit is in force.
 your Mac                                         shared
┌──────────────────────────────────┐        ┌──────────────────────────────┐
│ your tool ── adapter ─┐          │        │ governance repo (GitLab)     │
│                       ▼          │  git   │  grouping.yaml               │
│ Claude Code ─ MCP ─▶ sidecar ◀───┼────────┤  contracts/*.yaml            │
│ gromit CLI ────────▶ (signs,     │        │  approve/<commit>/<person>   │
│                       folds,     │        └──────────────────────────────┘
│                       queues)    │  wss   ┌──────────────────────────────┐
│                         ▲ ───────┼───────▶│ relay  wss://relay.example…  │
└─────────────────────────┼────────┘        │  stores and forwards events  │
                          │                 │  GitLab bridge ─▶ GitLab     │
       everyone else's ───┘                 │  Asana bridge  ─▶ Asana      │
       sidecars, same relay                 └──────────────────────────────┘

Grouping

A grouping is a team on the bus. The team's is tally. It is defined by one git repo, the governance repo (acme/tally-governance), holding:

yaml
grouping: tally
steward: tom
relay: wss://relay.example.com/
members:
  - person: tom
    forge: { gitlab: tom, asana: "1200000000000001" }   # how bridges recognise you
    devices:
      - { name: tom-laptop, key: "ed25519:0dbf10…" }
    # roles: [lead]          optional; contracts can grant rights to role:lead
    # on_bus: false          a person bridges may act for who runs no sidecar
bridges:
  - actor: "system:gitlab-bridge"
    mirrors: gitlab
    repos: { platform: acme/platform, pipelines: acme/pipelines, tools: acme/tools }
    contracts: [change-set@0, decision@0]
    key: "ed25519:…"
contracts: [change-set@0, decision@0, mandate@0, work-item@1]
governance:
  - paths: ["contracts/**", "extensions/**"]
    quorum: { steward: true, majority: true }
  - paths: ["grouping.yaml#members"]
    quorum: { all_except: subject }
  - paths: ["grouping.yaml#governance", "grouping.yaml#steward"]
    quorum: { unanimous: true }

Changing the rules

Anyone with push access commits to the governance repo's main. Pushing activates nothing. Members approve with gromit approve <commit>, which pushes a tag approve/<commit>/<person> signed with their device key. The newest commit whose approvals meet the governance: quorum for everything changed since the active commit becomes active. A path no rule names needs everyone. gromit rules status shows what is still missing.

So adding a contract is a commit adding contracts/<name>@<major>.yaml, then the steward plus a majority approving it (the contracts/** rule). Also listing it in grouping.yaml contracts: touches a path no rule names, so that edit needs everyone's approval. Do it as a separate commit, or leave it out.

Every event names the rules it was written under: a hash of grouping.yaml plus the contract files (the bundle). Each event is judged by the bundle it names. An event naming a bundle more than 24 hours after the next one took over is rejected as stale_rules.

Sidecar

Each person runs one sidecar per grouping, as a launchd agent (com.gromit.sidecar). It:

Tools, adapters and agents only ever talk to their own person's sidecar. See sidecar-api.md.

Relay

The relay (wss://relay.example.com/) stores every signed event and sends each one to every connected sidecar. It checks that the signer is a member under the active rules and that each event is the next one in its author's feed. It stamps received_at, the one clock every time rule uses. It does not fold. It also runs the two bridges.

Events

Everything on the bus is an event: one signed act by one actor on one entity. A real one, as the sidecar's event stream shows it:

json
{
  "id": "1220fc4d0bb4…",                        // hash of the signed fields
  "grouping": "tally",
  "contract": "work-item@1.1.0",
  "rules": "12200d654b0f…",                     // the bundle it was judged under
  "kind": "fact",
  "verb": "created",
  "entity": null,                               // absent on the event that creates the entity
  "actor": "system:asana-bridge",
  "person": "system:asana-bridge",
  "author": "ed25519:f50d29e7…",                // the signing device key
  "seq": 1121, "prev": "12202f1ee820…",          // the author's feed: a hash chain
  "seen": [],                                   // events the author had seen, for concurrency
  "ts": "2026-11-18T15:27:22.617Z",             // advisory only
  "received_at": "2026-11-18T15:27:23.901Z",    // stamped by the relay
  "payload": { "title": "chore(infra): rotate kath_home developer IP…",
               "repo": "git:platform",
               "ext.asana": { "gid": "1220673936359433", "url": "https://app.asana.com/…" } },
  "sig": "83ff3781…"
}

Fold

The fold replays every event through its contract and produces the current state: each entity's fields, each open handshake and each event's outcome. Every sidecar folds the same events with the same rules, so everyone sees the same state, whatever order events arrived in. Contract tests check this by folding each test in 12 shuffled orders.

When two events conflict, the one with the lower hash wins and the other forks. Two people claiming the same work item at once is the usual case.

Each event gets one outcome: applied, suggestion, claim, pending, fork or rejected:<reason>. See outcomes.md.

Actors

Actor Looks like Who Signs with
Person sam a member in grouping.yaml their device key, via their sidecar
Agent sam/claude, tom/reader software acting for a person the person's device key; needs a mandate
Bridge system:gitlab-bridge a mirror of a shared system, listed under bridges: its own key; only its listed contracts and repos

An adapter publishes as its person (sam), or as one of their agents (sam/todo) if you want its events marked as automated and limited by a mandate.

Agents and mandates

An agent can do nothing until its person grants a mandate@0. A grant names scopes such as work-item@1:routine (every routine verb), work-item@1:commitment (every commitment), work-item@1:claimed (one verb) or work-item@1:*. Attestations, such as decision@0:inferred, are only covered by a grant that names the verb. Every verb has a weight:

gromit local install grants <you>/claude the default mandate: routine verbs on work-item@1, change-set@0 and decision@0.

Bridges

A bridge is a system actor that mirrors a shared system onto the bus, so nobody needs their own adapter for it. Both bridges run inside the relay:

A bridge acts for a member through on_behalf and finds members by their forge: usernames. Someone with no mapping isn't mirrored. A bridge can only publish the contracts and repos grouping.yaml gives it, and only verbs whose who names bridge.

Adapters

An adapter connects one person's own tool. It runs on their machine, talks to their sidecar, and publishes as them. The Tiphys adapter (gromit-tiphys) is the first one. It turns Argonauts batches into work items and brings tickets back as seeds. An adapter in another language uses the same API. See writing-an-adapter.md.

Adapters and bridges never publish the same thing twice. The bridge owns change sets (one per MR). An adapter links its own planning to them through part_of and never opens one.

Visibility

Every event goes to the whole grouping today. The protocol allows narrower audiences, but that is switched off until seed:861 is fixed. A narrower event would break excluded members' copies of the author's feed. The sidecar refuses an audience narrower than grouping. So publish nothing you wouldn't show the whole team.