# Concepts

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

```
 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:

- `grouping.yaml`: who the members are, their device keys, their forge
  usernames and the bridges. Its `contracts:` list is informational: it
  names the contracts the default agent mandate covers, and decides nothing
  else.
- `contracts/*.yaml`: one file per contract, such as `work-item@1.yaml`.
  **Every contract file in the active commit is in force**, listed or not.
- `extensions/`: reserved for shared extension schemas. Empty today.

```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:

- holds the person's device key and signs every event they publish;
- keeps a clone of the governance repo and follows its active rules;
- keeps the whole event log in `~/.local/share/gromit/<grouping>/gromit.db`
  and queues events while offline;
- **folds** the log through the contracts into current state on every read;
- judges every event before sending it. One its own fold would reject never
  leaves the machine. The caller still gets the outcome;
- serves a local HTTP API on `~/.local/share/gromit/<grouping>/sidecar.sock`,
  an MCP server for agents (`gromit mcp`) and the `gromit` CLI.

Tools, adapters and agents only ever talk to their own person's sidecar.
See [sidecar-api.md](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…"
}
```

- An **entity** is identified by the id of the event that created it.
  Later events name it in `entity`. Ids are long. The API and CLI accept any
  unique prefix.
- A **response** (`accept`, `approved`) names the handshake it answers in
  `responds_to`.
- Events are never edited or deleted. A `redacted` event can blank a field's
  content while keeping the hash chain valid.

## 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
`fork`s. 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](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**:

- `routine`: applies at once.
- `commitment`: held as `pending` until the person ratifies, unless the
  grant says `ratify: none`. It lapses after `ratify_within`, 24h by default.
- `protected`: never by an agent. Approving a change set is an example. If
  a grant covers the verb the result is `rejected:requires_human`; if none
  does, `rejected:no_mandate` comes first.

`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:

- **GitLab bridge** (`system:gitlab-bridge`). Each MR in a listed project
  becomes a `change-set@0` held by its author, with reviews mirrored as
  `review_requested` and `approved`. A `## Decisions` section in an MR
  description becomes `decision@0` events.
- **Asana bridge** (`system:asana-bridge`). Tasks on the boards mapped to a
  bus repo become `work-item@1`, with the Asana ids in `ext.asana`. It works
  both ways: a work item created on the bus in that repo is written to the
  board.

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](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.
