@joe-broadhead/messaging 0.7.0 → 0.7.1

package/dist/spec/messaging-v1.md

@@ -16,8 +16,8 @@ other, exchange messages, and delegate A2A tasks, through a relay that only sees
   (`urn:messaging:binding:relay:v1`), presence and session addressing, delivery receipts, and the
   extensions `urn:messaging:ext:provenance:v1` and `urn:messaging:ext:presence:v1`.
 
-Not in v1: hole-punched peer-to-peer transport, federation between relays, payments, and group
-(multicast) encryption.
+Not in v1: hole-punched peer-to-peer transport, federation between relays, and payments. Conversations
+(§16) encrypt to many members with sender keys; MLS is left to a later protocol version.
 
 ## 2. Encodings
 
@@ -54,8 +54,9 @@ Not in v1: hole-punched peer-to-peer transport, federation between relays, payme
   `messaging/1/invite\n`, `messaging/1/invite-join\n`, `messaging/1/delegation\n`, `messaging/1/grant\n`,
   `messaging/1/card\n`, and for hosted realms (§15) the person hash prefix
   `messaging/1/person\n`, `messaging/1/dir-read\n`, `messaging/1/device-log\n`, `messaging/1/device-keys\n`,
-  `messaging/1/device-link\n`, `messaging/1/epoch\n` and `messaging/1/dir-key\n`). A signature or hash for
-  one purpose never verifies for another.
+  `messaging/1/device-link\n`, `messaging/1/epoch\n` and `messaging/1/dir-key\n`, and for conversations (§16) the
+  event signature prefix `messaging/1/conv-event\n` and the hash prefixes `messaging/1/conv-genesis\n`,
+  `messaging/1/dm\n` and `messaging/1/self\n`). A signature or hash for one purpose never verifies for another.
 - **Hash:** SHA-256, base64url.
 
 ## 3. Identity
@@ -2093,11 +2094,36 @@ it, in its `kv` table. The relay keeps `generation` and `min_reader` in its `met
 the tables Litestream adds when it replicates the database (`_litestream_*`) do not count. It opens
 any other store only when the store records its own generation and a `min_reader` at most its own schema. It
 refuses every other store and changes nothing in it, and the error says how to start over: stop the daemon or
-relay, move the home (or the relay database, with its `-wal` and `-shm` files) aside, and set it up again
-(`messaging-relay` logs it as `relay.store_refused {db, reason}` and exits 1). A
+relay, move the home (or the relay database, with its `-wal` and `-shm` files) aside, and set it up again. A
 daemon checks the store before it reads or writes anything else in its home. Nothing deletes a home or a
 database by itself.
 
+**A refused store** is machine-readable, so that a client never matches the wording. Every refusal has one of two
+**reasons**, and the remedy depends on it:
+
+| Reason | The store | Remedy |
+|---|---|---|
+| `pre-reset` | records no store generation, or another generation than the reader's | Start over: move the home (or the relay database) aside and set it up again. |
+| `newer` | its `min_reader` is above the reader's schema: a newer messagingd or relay wrote it | Upgrade the daemon or relay, and keep the home or database as it is. Never move it aside for this reason. |
+
+- `messagingd` exits with status **78** (`EX_CONFIG` of sysexits(3); `STORE_REFUSED_EXIT` in `@messaging/core`)
+  for either reason, and prints one line on stderr, `messagingd: store_refused: <reason>: <why, and what to do>`.
+  No other failure exits 78.
+- `messaging-relay` exits 78 and logs one JSON event, `relay.store_refused {db, reason, message}`: `reason` is
+  `pre-reset` or `newer`, and `message` is the text.
+- A client that starts the daemon and sees it exit 78 reports the error code `store_refused` (§13), with the reason
+  in a field of its own (`StoreRefusedError.reason`; `reason` in `messaging --json` errors and in agent tool
+  errors). It reads the reason from the two tokens after `messagingd:` on the line that start printed
+  (`storeRefusedReason` in `@messaging/core`) and never parses the text after them, which may change between
+  releases. A line without a reason token gives `store_refused` without a reason. `messaging daemon start` does
+  this.
+- A client offers to start over (moving the home aside) **only for `pre-reset`**. For `newer`, and for a refusal
+  without a reason, it tells the person to upgrade or to read messagingd's line, and moves nothing.
+- A home moved aside is named `<home>.pre-reset-<UTC timestamp>`, the timestamp as `YYYYMMDDTHHMMSSZ` (for example
+  `~/.messaging.pre-reset-20261108T171500Z`). The name carries no version, so it holds for every reset, and a
+  client that denies its agents the home also denies `<home>.pre-reset-*`: the moved home keeps the old keys and
+  messages. The messagingd that wrote it still opens it.
+
 **When stores grow.**
 
 - A daemon or relay opens any store of its generation whose `min_reader` is at most its own schema. It
@@ -2319,6 +2345,10 @@ callers rely on.
   It answers from what this machine has verified, synchronously; a caller catches up before it
   verifies. `Roster` implements it: `realm` is the team id, `device` is `member`, `anchor()` is
   `rosterAnchor`.
+- Conversations (§16): `checkVia`, `currentLinks`, `signConvEvent`, `verifyConvEvent`, `sealConvMsg`, `openConvMsg`, `sealConvMeta`,
+  `openConvMeta`, `sealKeyShares`, `openKeyShares`, `ConvLog.apply`, `ConvLog.applyExpired`, `ConvLog.relate`
+  and `resolveContext` throw only `MessagingError`. `ConvLog.at(seq)` is the state a log holding only entries 1
+  to `seq` has. `ReceiverChains.messageKey` hands out each message key once.
 - `createGrant` narrows its parent and never widens it (`forbidden`); an expired parent is `expired`.
 - Consent (§6.9): `signConsentGrant` refuses a grant that breaks a rule (`invalid_request`) or is
   over `LIMITS.grantBytes` (`too_large`); `verifyConsentGrant` checks the schema, the rules, the
@@ -2812,6 +2842,8 @@ contacts, changes devices or administers a team or channel.
 | binding_invalid | a device binding, a device-log entry or its authority failed verification (§15) |
 | jelly_unavailable | Jelly ID's key set or key history could not be fetched (§15.2); never reported as `binding_invalid` |
 | log_conflict | a device-log entry does not extend the log's head (§15.3); resync and retry |
+| conv_conflict | a conversation entry does not extend the log, or an event's op head is not the current op (§16.7); re-read and retry |
+| stale_epoch | a conversation message is sealed under an epoch that is not the current one, or a rekey is due (§16.7); re-seal and retry |
 | device_limit | the person already has `LIMITS.devicesPerPerson` current devices (§15.3) |
 | admission_required | `dir.bind` of an entry that is not a device binding itself with a `jelly` authority (§15.10) |
 | admission_invalid | `dir.bind` whose Jelly token is not live now, or not for this directory's issuer, resource and person (§15.10) |
@@ -2826,6 +2858,7 @@ contacts, changes devices or administers a team or channel.
 | ticket_invalid | `deployment: "jelly"`: the session ticket did not verify, is out of its lifetime, or names another session or agent (§8.11) |
 | daemon_unavailable | a client cannot reach the daemon |
 | daemon_mismatch | the daemon on the socket is another release or IPC protocol than the client, or did not say which (§8.2) |
+| store_refused | messagingd refused the home's store and changed nothing; it exits 78 (§8.8). Its `reason` field says why: `pre-reset` (no or another store generation: start over by moving the home aside) or `newer` (a `min_reader` above its schema: upgrade, keep the home); absent when messagingd named none. A client code: a client that starts the daemon reports it, never the daemon over IPC |
 | internal | unexpected failure (details stay in local logs) |
 
 ## 14. Versioning
@@ -3424,3 +3457,288 @@ five minutes, until it answers, so a new directory becomes ready without waiting
 `dir_wakes`: each Jelly host's device's armed wake ticket, its `agents` and `awaiting`, its `exp` and when it may
 next be presented (§7, "Wake tickets"). At start the directory rebuilds the map and the epoch log from them
 and refuses to start if they disagree with the last tree head.
+
+## 16. Conversations
+
+A conversation is one hash-chained log of signed events that the relay sequences and members verify. Membership,
+roles, epochs and settings are a function of the log. Message bodies are sealed under per-device sender keys, so a
+post is one ciphertext whatever the number of members. The schemas are in `schema/conversation.ts`, the rules in
+`conversation/` of core, and the vectors in `docs/spec/vectors/conversation.json`. The relay frames, the daemon's
+storage and the IPC surface that carry them are not specified yet; `docs/design/conversations.md` describes them.
+Until they land, chats are as §6.8 says.
+
+### 16.1 Identifiers
+
+- A **participant** (`ParticipantId`) is a person (§3, §15.1) or one agent of a person: `person/agent`, where
+  `agent` is a session name (§3). Every agent belongs to one person, its **person**.
+- A conversation id (`ConvId`) is one of:
+  - a **dm**: `"d_" + base32lower(SHA-256("messaging/1/dm\n" || JCS([a, b] sorted)))[0..26]`, where `a` and `b`
+    are its two participants, sorted by UTF-16 code units. Both ends derive the same id. `a` may equal `b`: a
+    person's note to themselves.
+  - a person's **self** conversation: `"s_" + base32lower(SHA-256("messaging/1/self\n" || JCS(person)))[0..26]`.
+  - a **group** or **channel**: `"c_"` and a ULID its creator chooses.
+
+  base32lower is RFC 4648 §6 in lower case without padding, as for `PersonId` (§15.1).
+- Kinds (`ConvKind`): `dm`, `group`, `channel` and `self`. Only a channel has a visibility (`public` or
+  `private`). The history policy (`none` or `shared`) says whether a late joiner may read earlier messages.
+- Roles (`ConvRole`): `owner`, `admin`, `member` and `guest`. A participant's state is `member`, or `invited`
+  until it accepts or is seated (§16.7).
+
+### 16.2 Events and the log
+
+Every event has a header and a body. The header is:
+
+```text
+{v: "messaging/1", realm, cid, id, by: {person, device, agent?}, ts, opHead: {seq, hash}, seen?: {seq, hash},
+ class, epoch?, idx?, wake?}
+```
+
+- `id` is a ULID the author chooses. It is unique in the conversation: the log refuses an event whose `id` it
+  already holds (`duplicate`). Other events refer to an event by `id`.
+- `by` names the signing device, its person and, for an agent's event, the agent. `by.device` must be a usable
+  Ed25519 key (§3).
+- `opHead` is the last op the author applied: its `seq` and `h(seq)`, or `{0, h(0)}` before any.
+- `seen` is the head the author had, for gossip (§16.4).
+- `class` is:
+  - `op`: a control op in plaintext (`ConvOp`), because the relay routes and checks authority by it;
+  - `msg`: a sealed `MsgBody`, with the `epoch` and the ratchet index `idx` of its key (§16.5). `wake` (at most
+    `LIMITS.wakeHints` (5)) names sessions of `by.person` the event may wake; it is the only plaintext hint;
+  - `keys`: sender-key shares, each sealed to one device (§16.6).
+- `sig` covers the whole event: `Ed25519(by.device, "messaging/1/conv-event\n" || JCS(event without sig))`.
+- An event is at most `LIMITS.convEventBytes` (256 KiB) of JCS (`too_large`). Every object is strict: an unknown
+  member is `invalid_request`.
+
+The relay stores and serves **entries**: `{seq, prev, event}`, where `seq` counts from 1 and `prev` is `h(seq − 1)`.
+The relay does not sign entries; members verify the chain (§16.4).
+
+**Ops** (`ConvOp`): `create`, `add`, `accept`, `join`, `leave`, `remove`, `role`, `seat`, `settings`,
+`archive` and `rekey`.
+
+- `create` states the kind, the visibility (channels), the history policy, `retainDays` (1 to
+  `LIMITS.retainDaysMax` (365)), the org a public channel is open to, the participants as seats `{p, role,
+  device?, respondTo?}`, the permits `post`, `invite` and `pins` (`all` or `admins`; absent is `all`), and
+  `sealedMeta` (§16.5).
+- `add` names 1 to `LIMITS.convOpParticipants` (100) seats; `remove` names as many participants.
+- `seat` sets an agent participant's `device` (the device that hosts it) and `respondTo` (`self`, `members` or
+  `none`), and accepts its invite. Only an agent's seat carries `device` or `respondTo`.
+- `settings` changes the visibility, history, retention or permits. `archive {on}` archives or restores.
+- `rekey {epoch, cause}` starts the next epoch; `cause` is `removed`, `device`, `added`, `settings` or
+  `schedule`.
+
+### 16.3 Message bodies
+
+The plaintext of a `msg` event is one `MsgBody`, at most `LIMITS.convPlaintextBytes` (64 KiB) of JCS
+(`too_large`):
+
+- `line`: `text` (at most `LIMITS.lineChars` (40,000) UTF-16 code units), `format` (`plain` or `md`), and
+  optionally `thread` (the root's event id), `broadcast`, `mentions` (at most `LIMITS.mentions` (50)), `files`
+  (at most `LIMITS.files` (10) attachments), `parts` (up to 8 A2A data parts), `answers` (the mention it answers)
+  `grants` (at most `LIMITS.agentMentions` (5) delegation grants, §6.7) and `via` (§16.10).
+- `edit {target, text, mentions?}`, `delete {target}`, `react {target, key, on}` and `pin {target, on}`.
+- `task {task}`: a task as a thread. `request {to, message, delegation}` is the root, to an agent participant;
+  `status` and `artifact` carry the A2A update events (§6.2) and `cancel` and `followUp` the requester's, each
+  naming the root.
+- `receipt {target, stage}`: `delivered`, `handed_to_agent` or `read`.
+- `meta {name?, topic?, purpose?}` and `policy {agentContext?, bridges?}`, which sets one or both (§16.8, §16.10).
+- `sync {sync}`: a body of the person's `self` conversation, and only there.
+
+A mention is `{p}` (a participant), `{all: "channel"}` or `{all: "here"}`. An attachment names a blob, its own
+AES-256-GCM key and nonce, its SHA-256 and size (at most `LIMITS.blobBytes` (25 MiB)), a media type and a name.
+
+**The self conversation.** A person's `self` conversation has one participant, the person, and history `shared`.
+Its `sync` bodies (`SyncBody`) are `read {cid, upTo, thread?}`, `unread {cid, from}`, `prefs {cid, notify,
+muteUntil?, receipts?}`, `follow`, `save`, `draft`, `joined`, `grant` (a consent grant, §6.9, verified over its
+raw value), `context {rules}` (§16.8), `localRetention {cid, days}` and `keys {cid, shares}` (at most
+`LIMITS.keyShares` (512) chain keys) and `link {link}` (§16.10). The last writer wins by `seq`.
+
+### 16.4 The hash chain and gossip
+
+- `h(0) = SHA-256("messaging/1/conv-genesis\n" || JCS(cid))`.
+- `h(seq) = SHA-256(h(seq − 1) || SHA-256(JCS(event)))`, over the raw 32-byte digests.
+- A member checks `prev = h(seq − 1)` and the signature over the raw received event before it reads any field.
+- **Gossip.** A member compares an event's `seen` with its own log (`ConvLog.relate`): `ahead` past its head (it
+  fetches up to `seen.seq` first), `consistent` when its `h(seen.seq)` is `seen.hash`, `diverged` otherwise. A
+  divergence proves that the relay showed two members different logs; the signed event is the evidence. `seen`
+  at or past the event's own `seq` is `invalid_request`.
+- **Retention.** When the relay expires a `msg` or `keys` entry it keeps the entry's `seq`, `prev` and the digest
+  `SHA-256(JCS(event))`, so the chain stays verifiable (`ConvLog.applyExpired`). Ops never expire: an op head that
+  names an expired entry is `conv_conflict`, so a relay that withholds an op as expired is caught by the next op.
+
+### 16.5 Sender keys
+
+- **Chains.** A sender device keeps one chain per (conversation, epoch). From a chain key `ck_i`:
+  - the message key `mk_i = HKDF-SHA256(ikm = ck_i, salt = empty, info = "messaging/1/conv-msg", 32 bytes)`;
+  - the next chain key `ck_{i+1} = HKDF-SHA256(ikm = ck_i, salt = empty, info = "messaging/1/conv-chain", 32
+    bytes)`.
+
+  The first chain of an epoch starts at index 0 from 32 random bytes.
+- **Sealing a body.** `body = base64url(nonce || AES-256-GCM(mk_idx, nonce, JCS(MsgBody), aad = JCS(header)))`,
+  with a fresh 12-byte nonce and the 16-byte tag last; the header is the event without `body` and `sig`. The
+  event's `epoch` and `idx` name the key. A message key seals one body only.
+- **Sealed meta.** `create.sealedMeta` is `JCS({name?, topic?, purpose?})` sealed the same way under the creator
+  device's epoch-0 key `mk_0`, with the create event's header as AAD. The creator's first message uses index 1.
+- **Rotation.** A sender starts a new chain in the same epoch after `LIMITS.chainMessages` (500) messages on one
+  chain, or `LIMITS.chainMaxMs` (7 days) after starting it. The new chain starts from fresh random bytes at the
+  next index, so `(epoch, device, idx)` names every key: the share with the greatest index at or below `idx`
+  derives it.
+- **Receiving.** A receiver derives forward only and uses each message key once. To open messages that arrive out
+  of order it keeps at most `LIMITS.skippedKeys` (1000) derived but unused keys per (epoch, sender device),
+  dropping the lowest indexes first; a message further than that past the chain is `too_large`, and one whose key
+  is used or dropped is `not_found`. It keeps each share's chain key at the share's index, to share history (§16.6).
+- **Epochs.** A `rekey` op starts the next epoch. Each sender then starts a new chain and shares it only with the
+  devices of the participant persons at the rekey's `seq`.
+- Authenticity comes from the event signature, not from the key: a member who holds a sender key still cannot
+  write as another member. Within an epoch there is no post-compromise security: a copy of a device's state reads
+  every chain it held until the next rotation or epoch.
+
+### 16.6 Key shares
+
+A `keys` event's body is `{shares: [{to: {person, device}, epk, nonce, ct}]}`, one entry per recipient device
+(at most `LIMITS.keySharesPerEvent` (500); a larger share is split over several events). Each `ct` seals
+`JCS({shares: [KeyShare]})`, where a `KeyShare` is `{epoch, device, idx, ck}` (at most `LIMITS.keyShares` (512)):
+
+1. Generate an ephemeral X25519 key pair; `epk` is its raw public key, `nonce` 12 random bytes.
+2. `shared = X25519(eph_priv, recipient.enc)`, the recipient device's key as the realm verified it (§4, §15.7).
+3. `key = HKDF-SHA256(ikm = shared, salt = epk || recipient.enc, info = "messaging/1/seal", 32 bytes)`, as for
+   an envelope (§5, "Sealing").
+4. `ct = AES-256-GCM(key, nonce, JCS({shares}), aad = JCS({header, to}))`, with the tag last.
+
+The AAD binds a share to its event and its recipient: moving it to another event or device makes it fail. A
+receiver keeps the first share for a given (epoch, device, idx); a later one with another key changes nothing.
+
+### 16.7 Authority
+
+`ConvLog.apply` checks each entry, in order, against the state after every earlier entry, and a failed check
+changes nothing:
+
+1. I-JSON (§2, `invalid_request`) and size (`too_large`); the schema, the realm and the `cid` (`invalid_request`).
+2. The chain: `seq = head + 1` and `prev = h(head)` (`conv_conflict`).
+3. The signature over the raw event (`bad_signature`).
+4. When appending live (the relay, or a member checking a pushed event): `ts` within `LIMITS.clockSkewMs` of now
+   (`expired`), and `by.device` a current device of `by.person` in the realm (`unknown_device`).
+5. `id` not already in the log (`duplicate`); `seen` before the event (`invalid_request`).
+6. The first entry is `create`, and there is only one (`conv_conflict`).
+7. For an `op`: `opHead` is the current op (`conv_conflict`); `by.agent` is absent: an agent never writes an op
+   (`forbidden`). For a `msg` or `keys`: `opHead` names an op of this log, or `{0, h(0)}` (`conv_conflict`).
+8. The rules below. An author who is not a participant is `not_member`, one who lacks the authority `forbidden`, a
+   target that is not a message of this log `not_found`, and a target in the wrong state `invalid_state`.
+
+A participant **person** is the person of any participant, so the devices of a person whose agent sits in a
+conversation append its keys and rekeys. "Admin" below means `owner` or `admin`; an author's role is its own
+participant's.
+
+| Event | Allowed when |
+|---|---|
+| `create` | A **dm**: exactly two seats, both `member`, no visibility, org, permits or meta, history `none`, `cid` the derived one, and the author is the person of one seat. A **self**: one seat, the author as `owner`, `cid` the author's, history `shared`. A **group**: 3 to `LIMITS.groupParticipants` (50) distinct seats, no visibility or org. A **channel**: a visibility, and an org if public, at most `LIMITS.convParticipants` (1000) seats. In a group or channel the author is a seat as `owner`. |
+| `add` | A group or channel (never a dm or self). The author is a member, not a guest, and an admin when `invite` is `admins`. No seat is a current participant; only an owner adds an owner or an admin; the kind's limit holds (`too_large`). |
+| `accept` | The author's own participant is `invited`. |
+| `join` | A public channel the author is not in; live, the author's person is in the channel's org. |
+| `leave` | A group or channel; the author is a participant. Their agents leave with them. The last owner cannot leave while another person remains. |
+| `remove` | A group or channel. The author is an admin, and an admin never removes an owner; or the target is the author's own agent (whether or not the author is a participant). Removing a person removes their agents. The last owner cannot be removed. |
+| `role` | A group or channel. The author is an owner, or an admin setting `member` or `guest` on a participant who is not an owner. The last owner cannot be demoted. |
+| `seat` | The target is an agent participant whose person is the author. It becomes `member`. |
+| `settings`, `archive` | A group or channel; the author is an admin. Only a channel has a visibility, and a public one needs an org (`invalid_state`). |
+| `rekey` | The author's person is a member participant person; `epoch` is the current one plus 1 (`invalid_request`). The cause is due (`invalid_state`), or is `device`, or is `schedule` and the epoch began at least `LIMITS.rekeyScheduleMs` (30 days) before. |
+| any `msg` | The author's participant is a member; `epoch` is the current epoch and no rekey is due (`stale_epoch`). |
+| `line` | Not archived; an admin when `post` is `admins`. A guest may post. `thread` and `answers` name messages of the log. A line with `via` is a person's, never an agent's. |
+| `edit` | Not archived; the target is a line, not deleted, by the same participant (person and agent). |
+| `delete` | The target is a line or a task event, not deleted, and the author wrote it or is an admin. |
+| `react` | As `line`; the target is not deleted; at most `LIMITS.reactionsPerEvent` (50) keys per target (`too_large`). |
+| `pin` | Not archived; an admin when `pins` is `admins`; the target is not deleted; at most `LIMITS.pins` (100) pinned (`too_large`). |
+| `task` | A `request` as `line`, to a member agent participant (`not_found`). `status` and `artifact` from that agent; `cancel` and `followUp` from the requester. The root is a task request (`invalid_state`). |
+| `receipt` | The target is a message of the log. |
+| `meta` | Not in a dm; in a channel, an admin. |
+| `policy` | Not by an agent, and not in a `self` conversation. In a channel, an admin; in a dm or group, any participant person, as a vote. |
+| `sync` | Only in a `self` conversation, where no other body goes (`invalid_request`). |
+| `keys` | The author's person is a member participant person and `by.agent` is absent. Every share goes to a participant person (`forbidden`); live, to a current device of that person (`unknown_device`). |
+
+**State.** A participant starts as `member`, except an agent whose person is not the author (`invited` until its
+person seats it) and a `guest` (`invited` until they accept). Live, adding a person of another org as anything but a
+guest is `forbidden`. A rekey is **due** after a removal or a leave (cause `removed`), an add to a group (`added`),
+and a change of the history policy (`settings`); a channel does not rekey on add. While a rekey is due, every `msg`
+is `stale_epoch`: no message is sealed under a key a removed device holds. A `rekey` clears every due cause.
+
+`ConvLog` keeps the state after every entry: `at(seq)` is the state of a log holding only entries 1 to `seq`. Ops
+and `policy` change it; the rules that read a message body (edit, delete, reactions, pins, tasks) run only when the
+caller passes the opened body, so the relay, which cannot open bodies, applies the header rules alone.
+
+### 16.8 Agents and history as context
+
+A person decides which of their agents may mine which of their conversations as context, and a conversation's
+policy decides whether members' agents may mine it at all.
+
+- **Policy** (`AgentContext`): `members` (members' agents may, each under its person's rules), `seats` (only
+  agents seated in it, by their seats) or `none`. The default is `members`. In a channel an admin sets it with a
+  `policy` body; in a dm or group each participant person votes, and the strictest vote counts (`none` <
+  `seats` < `members`). A person's vote goes when they leave.
+- **Rules** (`ContextRule`): `{agent, scope, access, lookbackDays?}`, where `agent` is a session name or `*`,
+  `scope` is `{cid}` or `{kind}` with `kind` one of `own`, `dm`, `group`, `channel.private` and
+  `channel.public`, and `access` is `allow`, `ask` or `off`. A person holds at most `LIMITS.contextRules` (500),
+  one per (agent, scope), synced in their `self` conversation. A conversation is `own` when its participant persons
+  are the person alone.
+- **Resolution** (`resolveContext`) for agent A of person P reading conversation C as context:
+  1. a `self` conversation is never mined;
+  2. C's policy `seats` or `none` forbids the read, whatever P's rules say;
+  3. else the most specific rule of P applies (a `cid` scope over a `kind` scope, then A by name over `*`), or
+     with none, the default for C's scope:
+
+     | Scope | Access | Lookback |
+     |---|---|---|
+     | `own` | `allow` | the retention |
+     | `channel.public` | `allow` | 90 days |
+     | `channel.private` | `ask` | 30 days |
+     | `group` | `ask` | 30 days |
+     | `dm` | `ask` | 14 days |
+
+     `off` forbids, `ask` holds the read for P to answer, `allow` serves it;
+  4. the lookback is the smallest of the rule's (or default's) lookback, C's `retainDays` and P's local
+     retention for C.
+- An agent seated in C reads C from its seat by its seat, not by P's rules, unless C's policy is `none`; then it
+  reads only what is addressed to it and the threads that is in (`seatReads`).
+- Agents of every client follow these rules, MCP clients included; each daemon enforces them for its own person's
+  agents.
+
+### 16.9 Limits
+
+| Limit | Value |
+|---|---|
+| `LIMITS.convParticipants` | 1000 participants (persons and agents) in a channel |
+| `LIMITS.groupParticipants` | 50 in a group |
+| `LIMITS.convOpParticipants` | 100 per `add` or `remove` |
+| `LIMITS.convEventBytes` | 256 KiB per event |
+| `LIMITS.convPlaintextBytes` | 64 KiB per message body |
+| `LIMITS.lineChars` | 40,000 UTF-16 code units |
+| `LIMITS.mentions`, `LIMITS.files`, `LIMITS.agentMentions` | 50, 10 and 5 per line |
+| `LIMITS.blobBytes` | 25 MiB per file |
+| `LIMITS.reactionsPerEvent`, `LIMITS.pins` | 50 keys per target, 100 pins per conversation |
+| `LIMITS.retainDaysDefault`, `LIMITS.retainDaysMax` | 90 days, 365 days |
+| `LIMITS.skippedKeys`, `LIMITS.chainMessages`, `LIMITS.chainMaxMs` | 1000, 500, 7 days |
+| `LIMITS.rekeyScheduleMs` | 30 days |
+| `LIMITS.keyShares`, `LIMITS.keySharesPerEvent` | 512 chain keys per share, 500 devices per `keys` event |
+| `LIMITS.wakeHints`, `LIMITS.contextRules` | 5, 500 |
+
+### 16.10 Linked channels (reserved)
+
+A person may link an outside chat account (Telegram, then Slack) as an alias of themselves, to reach their own
+agents from a phone. The fields below are part of the schema and are validated, but no daemon acts on them yet;
+`docs/design/conversations.md` §17 describes the plan.
+
+- **`via {channel}`** on a `line`: the person wrote it from a linked channel, `telegram` or `slack`. It is sealed and
+  signed with the event, so every member sees it. Only a person writes it (`forbidden` on an agent's line, §16.7).
+  The person's own devices also check it against the person's links (`checkVia`): a link of that channel, hosted by
+  the authoring device, in force. Other members cannot see the links and do not check that.
+- **`link`**, a body of the person's `self` conversation: `{id, channel, account, host, proof, authority, linkedAt,
+  revokedAt?}`.
+  - `account` is the channel's id for the person's account; it is never in the device log, the directory or
+    presence.
+  - `host` is the device that runs the bridge.
+  - `proof` is `{method: "code-sas", codeDigest, sas}`: the digest of the one-time code and the six-digit code the
+    person matched on both sides.
+  - `authority` is a non-empty subset of `chat` and `view` (§8.11), and never more.
+  - For each `id` the record written last is the one in force, unless it has `revokedAt` (`currentLinks`).
+- **`bridges`** in `policy`: who may mirror the conversation to a linked channel: `none` (the default), `admins` or
+  `members`. In a channel an admin sets it. In a dm or group the strictest vote of the participant persons counts,
+  and a person who has not voted counts as `none`, so bridging needs every participant person's vote.
+- **Reader ids** (`ReaderId`): a person, or `ext:<channel>:<link id>` for a link's channel provider. They are not on
+  the wire; the audience guard's reader sets use them.
+- A foreign sender on a bridged channel (`via.sender`) is not part of v1: the schema refuses it.

package/dist/types/core/agent-tools.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { TaskState as A2ATaskState } from "./schema/a2a.js";
-import { ErrorCode } from "./schema/errors.js";
+import { ErrorCode, StoreRefusedReason } from "./schema/errors.js";
 /**
  * The agent tool contract (spec §11, "Agent tools"): the eight tools every agent-facing client
  * offers, with one input and one output schema each. The OpenCode plugin registers them as
@@ -81,6 +81,11 @@ export declare const DONE_STATES: readonly TaskStateName[];
  * starts with the code, and `remedy` is "Next: " and this sentence.
  */
 export declare const TOOL_REMEDIES: Readonly<Record<ErrorCode, string>>;
+/**
+ * `store_refused`'s remedy by its reason (spec §8.8), which replaces `TOOL_REMEDIES.store_refused` when the reason is
+ * known: only `pre-reset` moves the home aside; `newer` upgrades messagingd and keeps the home.
+ */
+export declare const STORE_REFUSED_REMEDIES: Readonly<Record<StoreRefusedReason, string>>;
 export declare const ToolErrorBody: z.ZodObject<{
     error: z.ZodObject<{
         code: z.ZodEnum<{
@@ -111,6 +116,8 @@ export declare const ToolErrorBody: z.ZodObject<{
             binding_invalid: "binding_invalid";
             jelly_unavailable: "jelly_unavailable";
             log_conflict: "log_conflict";
+            conv_conflict: "conv_conflict";
+            stale_epoch: "stale_epoch";
             device_limit: "device_limit";
             admission_required: "admission_required";
             admission_invalid: "admission_invalid";
@@ -125,10 +132,15 @@ export declare const ToolErrorBody: z.ZodObject<{
             ticket_invalid: "ticket_invalid";
             daemon_unavailable: "daemon_unavailable";
             daemon_mismatch: "daemon_mismatch";
+            store_refused: "store_refused";
             internal: "internal";
         }>;
         message: z.ZodString;
         remedy: z.ZodString;
+        reason: z.ZodOptional<z.ZodEnum<{
+            "pre-reset": "pre-reset";
+            newer: "newer";
+        }>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type ToolErrorBody = z.infer<typeof ToolErrorBody>;
@@ -136,7 +148,7 @@ export type ToolErrorBody = z.infer<typeof ToolErrorBody>;
  * The body of a tool error in Jelly's house style (§13.14): `message` starts with the code, `remedy` is
  * the code's one next step. `message` must never hold peer text, bodies or keys.
  */
-export declare function toolErrorBody(code: ErrorCode, message: string): ToolErrorBody;
+export declare function toolErrorBody(code: ErrorCode, message: string, reason?: StoreRefusedReason): ToolErrorBody;
 export declare const ToolFiles: z.ZodArray<z.ZodObject<{
     name: z.ZodString;
     mime: z.ZodString;
@@ -465,6 +477,8 @@ export declare const AgentTool: {
                     binding_invalid: "binding_invalid";
                     jelly_unavailable: "jelly_unavailable";
                     log_conflict: "log_conflict";
+                    conv_conflict: "conv_conflict";
+                    stale_epoch: "stale_epoch";
                     device_limit: "device_limit";
                     admission_required: "admission_required";
                     admission_invalid: "admission_invalid";
@@ -479,6 +493,7 @@ export declare const AgentTool: {
                     ticket_invalid: "ticket_invalid";
                     daemon_unavailable: "daemon_unavailable";
                     daemon_mismatch: "daemon_mismatch";
+                    store_refused: "store_refused";
                     internal: "internal";
                 }>>;
                 expect: z.ZodOptional<z.ZodEnum<{
@@ -727,6 +742,8 @@ export declare const AgentTool: {
                         binding_invalid: "binding_invalid";
                         jelly_unavailable: "jelly_unavailable";
                         log_conflict: "log_conflict";
+                        conv_conflict: "conv_conflict";
+                        stale_epoch: "stale_epoch";
                         device_limit: "device_limit";
                         admission_required: "admission_required";
                         admission_invalid: "admission_invalid";
@@ -741,6 +758,7 @@ export declare const AgentTool: {
                         ticket_invalid: "ticket_invalid";
                         daemon_unavailable: "daemon_unavailable";
                         daemon_mismatch: "daemon_mismatch";
+                        store_refused: "store_refused";
                         internal: "internal";
                     }>>;
                 }, z.core.$strip>>>;

package/dist/types/core/conversation/context.d.ts

@@ -0,0 +1,56 @@
+import type { PersonId, SessionName } from "../schema/common.js";
+import { type AgentContext, type ContextAccess, type ContextKind, type ContextRule, type ConvId, type ConvKind, type Visibility } from "../schema/conversation.js";
+/** The defaults that apply where a person has no rule (decided 2026-11-08). `lookbackDays` absent: the retention. */
+export declare const CONTEXT_DEFAULTS: Readonly<Record<ContextKind, {
+    access: ContextAccess;
+    lookbackDays?: number;
+}>>;
+/** The facts about a conversation that resolution reads. `persons` are its participant persons at the read. */
+export interface ContextConv {
+    cid: ConvId;
+    kind: ConvKind;
+    visibility?: Visibility;
+    persons: readonly PersonId[];
+    retainDays: number;
+    agentContext: AgentContext;
+}
+/**
+ * The scope a conversation falls in for `person`: `own` when its participant persons are `person` alone, else its
+ * kind (a channel by its visibility). A `self` conversation has none: no agent mines it.
+ */
+export declare function contextKindOf(person: PersonId, conv: Pick<ContextConv, "kind" | "visibility" | "persons">): ContextKind | undefined;
+/**
+ * The person's rule for (agent, conversation), most specific first: a `cid` scope over a `kind` scope, then a named
+ * agent over `*`. Undefined when no rule matches; the defaults then apply.
+ */
+export declare function matchContextRule(rules: readonly ContextRule[], agent: SessionName, cid: ConvId, kind: ContextKind): ContextRule | undefined;
+/** The outcome of a context read: served, held for the person (`ask`), or refused. */
+export type ContextDecision = {
+    access: "allow" | "ask";
+    lookbackDays: number;
+    source: "rule" | "default";
+} | {
+    access: "forbidden";
+    source: "policy" | "rule" | "self";
+};
+/**
+ * The effective rule for agent `agent` of `person` reading `conv` as context (not by its seat):
+ * - the conversation's policy `seats` or `none` forbids it, whatever the person's rule says;
+ * - else the person's rule, or the default: `off` forbids, `ask` holds, `allow` serves;
+ * - the lookback is the smallest of the rule's (or the default's) `lookbackDays`, the conversation's `retainDays`,
+ *   and the person's local retention for it.
+ * Throws `invalid_request` for a rule set that fails `ContextRules`.
+ */
+export declare function resolveContext(args: {
+    person: PersonId;
+    agent: SessionName;
+    conv: ContextConv;
+    rules: readonly ContextRule[];
+    localRetentionDays?: number;
+}): ContextDecision;
+/**
+ * What a seated agent reads by its seat (spec §16.8): everything from its seat's `seq` on, unless the policy is
+ * `none`, when it reads only the events addressed to it and the threads they are in. The person's rules do not
+ * apply to seat reads.
+ */
+export declare function seatReads(agentContext: AgentContext): "conversation" | "items";

package/dist/types/core/conversation/event.d.ts

@@ -0,0 +1,36 @@
+import type { Identity } from "../identity.js";
+import { type Hash } from "../schema/common.js";
+import { type ConvEvent, type ConvEventHeader, type ConvId, type UnsignedConvEvent } from "../schema/conversation.js";
+/** h(0) of `cid`'s log: SHA-256(DOMAIN.convGenesis ‖ JCS(cid)), base64url. */
+export declare function convGenesisHash(cid: ConvId): Hash;
+/** SHA-256(JCS(event)), the raw digest, as the chain links it. Throws `invalid_request` for non-I-JSON. */
+export declare function convEventDigest(event: unknown): Uint8Array;
+/** h(seq) = SHA-256(h(seq − 1) ‖ SHA-256(JCS(event))), over the raw 32-byte digests, base64url. */
+export declare function convEntryHash(prev: Hash, event: unknown): Hash;
+/** `convEntryHash` from the event's digest: what a member checks for an entry whose content has expired. */
+export declare function convLinkHash(prev: Hash, digest: Uint8Array): Hash;
+/** The header of an event: everything but `body` and `sig`. JCS of it is the AAD of a sealed body. */
+export declare function convEventHeader(event: ConvEvent | Omit<ConvEvent, "sig"> | ConvEventHeader): ConvEventHeader;
+/**
+ * Checks that `raw` is I-JSON within `LIMITS.jsonDepth` and at most `LIMITS.convEventBytes` (`too_large`), that it
+ * matches `ConvEvent`, and that `by.device` is a usable Ed25519 key. Returns a frozen JSON copy of the raw value, so
+ * the signature and the hash cover exactly what was received. The signature is not checked.
+ */
+export declare function admitConvEvent(raw: unknown): ConvEvent;
+/**
+ * Signs an event (spec §16.4): `sig = Ed25519(by.device, DOMAIN.convEvent ‖ JCS(event without sig))`. `by.device`
+ * must be `identity`'s machine. Refuses an event that fails the schema (`invalid_request`) or is over
+ * `LIMITS.convEventBytes` once signed (`too_large`). Authority is checked when the event is applied.
+ */
+export declare function signConvEvent<E extends UnsignedConvEvent>(identity: Identity, unsigned: E): E & {
+    sig: string;
+};
+/** True only for a valid signature by `event.by.device` over the event without `sig`. Never throws. */
+export declare function convEventSigned(event: ConvEvent): boolean;
+/**
+ * Admits `raw` (`admitConvEvent`) and checks its signature over the raw value (`bad_signature`). Membership and
+ * authority are `ConvLog.apply`'s. Throws only MessagingError.
+ */
+export declare function verifyConvEvent(raw: unknown): ConvEvent;
+/** Freezes a JSON value and everything in it, iteratively. */
+export declare function deepFreeze<T>(value: T): T;

package/dist/types/core/conversation/ids.d.ts

@@ -0,0 +1,18 @@
+import { PersonId } from "../schema/common.js";
+import { type ConvId, ParticipantId } from "../schema/conversation.js";
+/**
+ * The id of the dm between `a` and `b`: `"d_" + base32lower(SHA-256(DOMAIN.dm ‖ JCS([a, b] sorted)))[0..26]`. Both
+ * ends derive the same id, so a dm has no create race. `a` may equal `b`: a person's note to themselves.
+ */
+export declare function dmConvId(a: ParticipantId, b: ParticipantId): ConvId;
+/** The id of `person`'s own `self` conversation: `"s_" + base32lower(SHA-256(DOMAIN.self ‖ JCS(person)))[0..26]`. */
+export declare function selfConvId(person: PersonId): ConvId;
+/** The person a participant is, or belongs to. */
+export declare function participantPerson(p: ParticipantId): PersonId;
+/** The agent's session name, for an agent participant. */
+export declare function participantAgent(p: ParticipantId): string | undefined;
+/** The participant an event's `by` names: `person`, or `person/agent`. */
+export declare function participantOf(by: {
+    person: PersonId;
+    agent?: string | undefined;
+}): ParticipantId;

package/dist/types/core/conversation/link.d.ts

@@ -0,0 +1,16 @@
+import type { MachineId, PersonId } from "../schema/common.js";
+import { type LinkRecord, type MsgBody, type ReaderId } from "../schema/conversation.js";
+/** The links in force: for each link id the record written last (records are in `seq` order), unless revoked. */
+export declare function currentLinks(records: readonly LinkRecord[]): LinkRecord[];
+/**
+ * Checks a line's `via` against the author's links, as the author's own devices can (other members cannot see the
+ * person's links): only a person writes from a linked channel, never an agent, and only through a link of that
+ * channel that the authoring device hosts and that is in force. Throws `forbidden`.
+ */
+export declare function checkVia(body: MsgBody, by: {
+    person: PersonId;
+    device: MachineId;
+    agent?: string;
+}, links: readonly LinkRecord[]): void;
+/** The reader id of a link's channel provider, for the audience guard: `ext:<channel>:<link id>`. */
+export declare function linkReader(link: Pick<LinkRecord, "channel" | "id">): ReaderId;