---
title: "Meeting events"
description: "Typed meeting events from the Meet adapters into the gateway: meeting_started / meeting_segment / meeting_ended / meeting_forget / meeting_opt_out on the owner-local [meet] socket, the per-line acks and closed refusal reasons, how segments land in the recall-by-clock timeline, retention, tombstones and the spoken forget / stop-recording verbs."
type: "living"
source: "docs/contracts/meeting.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **Living doc**, checked against the code 2026-11-14

meeting.v1 — typed meeting events into the Gateway's store

- Status: **gateway half built, off by default** (ADR 0039). The events travel on an owner-local unix socket between
  an adapter and the Gateway, not on the WebSocket protocol, so no client sees them.
- Producers: `meetctl` (the local two-leg path, `tools/meet/`) and `meet-cloud` (the Media API path,
  `tools/meet/meet_cloud.swift`). meet-cloud does not send to a Gateway yet. Consumer: the Gateway's meeting inlet
  (`crates/voice_gateway/src/meetings.rs`).
- Builds on ADR 0034's events-in contract (JSON lines, Vulpine's own names only) and the recall-by-clock timeline
  (`[retrieval] timeline_path`).
- Adapters decode; the Gateway owns the transcript store and the recall verbs. A stored segment answers
  `pi_recall_window` and "what was said at 22:30" like any other recall by clock. No raw audio and no vendor name
  cross this seam: a call is a Vulpine id, a leg is `near` or `far`, a speaker is a Vulpine label.


## Transport

- One unix socket, `[meet] events_socket` (default `meet/events.sock` in the state folder,
  `~/.local/state/vulpine`). The Gateway makes
  the directory owner-only (0700) and the socket 0600. A socket held by another live Gateway refuses the bind.
  Owner-local is the authority: there is no key.
- The inlet runs only when `[meet] enabled = true` **and** `[retrieval] timeline_path` is set (the segments go to
  that file). Without either, nothing listens.
- The adapter writes one JSON object per line. Each line is at most **16 KiB**. A longer line closes the
  connection. At most **4** connections at once.
- The Gateway answers **every** line with exactly one ack line, in order:

```json
{"ok":true,"type":"meeting_segment","call_id":"m-20261003-2230","seq":12,"stored":true}
{"ok":false,"type":"meeting_segment","call_id":"m-20261003-2230","seq":13,"reason":"call_opted_out"}
```

  `stored` is `false` on an accepted line that wrote nothing (a duplicate `seq`, a draft). An adapter need not read
  acks. One that does learns of a voice opt-out on its next segment (below).
- An optional first line `{"type":"hello","adapter":"meetctl","contract":1}` is acknowledged. A `contract` other than
  `1` is refused (`contract_mismatch`) and the connection closes. meet-cloud's hello names `"adapter":"meet-cloud"`.
  The Gateway reads only `contract`.

## The events

All times are **unix milliseconds on the adapter's clock**: the Gateway trace's clock when the adapter runs on the
Gateway's host.

### `meeting_started`

```json
{"type":"meeting_started","call_id":"m-20261003-2230","platform":"meet","started_at":1791090600000,"legs":["near","far"],"notice_given":true}
```

| field | rule |
|---|---|
| `call_id` | `[A-Za-z0-9][A-Za-z0-9._-]{0,63}` — a Vulpine id the adapter mints (meetctl's session id). Never a Meet space name or conference record id. |
| `platform` | `[a-z][a-z0-9_-]{0,23}` (`meet`, `zoom`, `browser`, `fixture`) |
| `started_at` | unix ms, after 2020-01-01 and no more than a day ahead of the Gateway's clock |
| `legs` | a non-empty subset of `near`, `far`, no repeats |
| `notice_given` | must be `true` (ADR 0039 §3: no capture before the notice). `false` is refused `notice_not_given`. A fixture replay sends `true`. |

A second `meeting_started` for an open call is acknowledged (`stored:false`). For a forgotten or opted-out call it is
refused (`call_forgotten` / `call_opted_out`): a tombstone cannot be re-imported.

### `meeting_segment`

```json
{"type":"meeting_segment","call_id":"m-20261003-2230","leg":"far","seq":12,"t0":1791091800000,"t1":1791091804200,"text":"Can we move it to Thursday?","speaker":{"label":"far-1","confidence":0.82}}
{"type":"meeting_segment","call_id":"m-20261003-2230","leg":"far","seq":14,"t0":1791091800000,"t1":1791091809000,"text":"Can we move it to Thursday at ten?","replaces":{"from_seq":12,"to_seq":13}}
```

| field | rule |
|---|---|
| `call_id` | a call this Gateway saw start (`call_not_started` otherwise) |
| `leg` | one of the call's `legs` (`leg_not_in_call`) |
| `seq` | per-call, increasing, `0 ≤ seq ≤ 10 000 000`; a `seq` already stored is a duplicate (acked, `stored:false`) |
| `t0`, `t1` | unix ms, `t0 ≤ t1`, `t1 − t0 ≤ 120 000`, `t0` not before the call's `started_at − 60 s` |
| `text` | 1–2 000 characters after trimming, no control characters |
| `speaker` | optional; `label` `[a-z][a-z0-9-]{0,23}` (`you`, `far-1`), `confidence` in `[0, 1]` |
| `replaces` | optional; `from_seq ≤ to_seq < seq`, at most 64 lines — the earlier lines are deleted and this one stands for them (the long-form re-decode's revision id) |
| `final` | optional, default `true`; a draft (`false`) is acknowledged and not stored |
| `source` | optional, default `local`; `google_artifact` (or any other value) is refused `source_not_stored` (ADR 0039 §2: Google's transcript is evidence, never the record). meet-cloud's own decode of the call audio is `local`, the default. |

A call holds at most **50 000** stored segments (`call_segment_cap`).

### `meeting_ended`

```json
{"type":"meeting_ended","call_id":"m-20261003-2230","ended_at":1791093600000,"reason":"call_left"}
```

`reason` is `[a-z][a-z_]{0,31}`. The known values are `call_left`, `adapter_stopped`, `leg_lost`, `cloud_lost`,
`error`. Late finals after `meeting_ended` are still accepted, because decode lags the call.

### `meeting_forget` and `meeting_opt_out`

```json
{"type":"meeting_forget","call_id":"m-20261003-2230"}
{"type":"meeting_opt_out","call_id":"m-20261003-2230"}
```

Both delete every stored segment of the call and its timeline session row, and leave **one text-free tombstone**
(`call_id`, `state` = `forgotten` | `opted_out`, the instant). Every later line for that call is refused with the
tombstone's reason. On either, the adapter deletes its own spool for the call (window WAVs and `windows.jsonl`); the
Gateway never holds that spool. The spoken verbs below do the same from the room.

## Refusal reasons (closed)

`bad_json`, `unknown_type`, `line_too_long`, `contract_mismatch`, `bad_call_id`, `bad_platform`, `bad_time`,
`bad_legs`, `notice_not_given`, `call_not_started`, `leg_not_in_call`, `bad_seq`, `bad_text`, `bad_speaker`,
`bad_replaces`, `bad_reason`, `source_not_stored`, `call_segment_cap`, `call_forgotten`, `call_opted_out`,
`store_unavailable`.

## In the store

- The call is a timeline session `meet/<call_id>`, source `meet`, spanning `started_at`–`ended_at`.
- Each segment is a timeline event at `t0`, kind `meet <speaker label or leg>`, text the segment's text. A recall
  window renders it as `- 22:30 meet far-1: Can we move it to Thursday?`. A side table keeps `(call_id, seq, t1)`
  for replacements and retention. The tombstones table holds no text.
- **Retention**: segments older than `[meet] segment_retention_days` (default and maximum **90**; a larger value is
  clamped) are swept when the inlet opens the store, with the emptied call sessions. The adapter deletes window audio
  after 7 days; the Gateway never sees it. Tombstones are kept.
- Trace: `<trace_dir>/meet.jsonl` carries started / ended / forget / opt-out / refusal rows and segment counts,
  never a segment's text and never a speaker's words.

## The spoken verbs (closed phrase sets)

Routed to the Gateway only while the inlet runs. Otherwise the words are the brain's.

| verb | phrases ("please" and the wake word dropped) | effect |
|---|---|---|
| forget | "forget this call / that call / the call", "forget this meeting / that meeting / the meeting" | `meeting_forget` on the current call |
| opt out | "stop recording", "stop recording this call / the call", "stop transcribing", "stop transcribing this call / the call", "don't (do not) transcribe this call", "don't (do not) record this call" | `meeting_opt_out` on the current call |

The current call is the latest started call that is open or ended within the last 15 minutes. With none, Vulpine
says so. The adapter learns of a voice opt-out from its next segment's ack (`call_opted_out`) and stops capture.

## Minutes (`pi_meeting_minutes`)

The brain tool `pi_meeting_minutes` takes a call id, or `last: true` for the most recent call. The gateway answers it
over the brain's mutation socket, not the events socket (request `meeting_minutes`, field `call_id` = the id or
`last`). Nothing is spoken.

- **Read**: the call's stored segments in time order. Each becomes a line `[mm:ss] <speaker label or leg>: text`,
  timed from the call's start. At most 60,000 characters go to the model. A longer call is cut at a line, and the cut
  becomes a doubt.
- **Model**: one tool-free prompt on the brain lane, with the dictation tidy's launch and a bound of
  `[brain] minutes_deadline_secs` (default 45 s, at most 50). The transcript goes between nonce delimiters as data.
  The prompt pack is a golden (`crates/voice_gateway/src/meeting_minutes_prompt.golden.txt`):
  - invent nothing;
  - a proposal is not a decision;
  - list only decisions explicitly made;
  - never attribute a line to a person whose label has no name;
  - a label gets a name only when the transcript states it, otherwise `unknown`;
  - a mandatory doubt section: misheard words, misunderstood points, unclear speakers, name variants.
- **Answer**: exactly one JSON object `{summary, decisions[], open_questions[], doubts[], speakers[{label, name}]}`.
  Anything else is `bad_output`. The gateway also enforces the speaker rules:
  - a speaker label the call does not have is dropped;
  - a label the model left out is listed as `unknown`;
  - a name the transcript never says becomes `unknown`, with a doubt line.
  - The doubt list is never empty, and the answer is bounded to 14 KiB.
- **Refusals**: `no_meetings`, `call_not_found`, `call_empty`, `call_forgotten`, `call_opted_out`. `last` never
  reaches past a tombstone newer than the newest call: when the most recent call was forgotten, it refuses and does
  not summarize an older call.
- **Trace**: `meeting_minutes` rows carry counts and reasons, never text. The model call ends in one
  `meeting_minutes {phase: outcome}` row: `ms` (the call), `segments_in`, `reply_bytes` (the model's answer, 0 when
  none came back), `guard {closed_json, unknown_names, doubts_n, capped}` (the answer parsed as the one closed object;
  names turned `unknown`; doubt lines returned; items dropped to fit the answer) and `outcome` (`ok`, `timeout` or
  `refused:<reason>`, e.g. `refused:bad_output`). On `ok` it also carries `decisions_n` and `open_questions_n`.
- **On request from the desktop**: `vulpine-glyphctl meet minutes [call_id|last]` and the **Minutes** button on
  Vulpine.app's Dictation tab run the same tool through the typed tool door. The door registers the call under its own
  `door-<uuid>` id. It hands the runner the session brain's mutation socket, token and call id in its environment
  (`VULPINE_TOOL_CALL_ID`; never on the command line), and answers the socket itself while the runner runs. The runner
  may live `[brain] tool_door_timeout_secs` (default 60 s, at least 10 s past the minutes deadline, checked at
  startup). A second minutes call while one is open on the session is refused with receipt code `busy`.
  vulpine-glyphctl prints the typed answer on one JSON line; it is its one verb that prints model text. The tab shows
  only the counts and the call id. The client-facing answer is bounded at the tool's 14 KiB plus a 1 KiB envelope.
- **Admin**: the events window (`GetEvents`) carries `last_minutes {call_id, decisions_n, open_questions_n,
  doubts_n, at_ms}` for the last minutes drafted since the gateway started. It is absent before the first.
