@joe-broadhead/messaging 0.7.0 → 0.8.0

package/dist/lib/modules/core/schema/conversation.js

@@ -0,0 +1,326 @@
+/**
+ * Conversations (spec §16): one log per conversation, sequenced by the relay, hash-chained and signed per event;
+ * sender keys for message bodies; pairwise sealed key shares; a person's `self` conversation; and the person's
+ * context rules for their agents. Every object is strict: an unknown member fails the schema.
+ *
+ *   sig    = Ed25519(by.device, DOMAIN.convEvent + JCS(event without sig))
+ *   h(0)   = SHA-256(DOMAIN.convGenesis + JCS(cid))
+ *   h(seq) = SHA-256(h(seq − 1) ‖ SHA-256(JCS(event))), over the raw 32-byte digests
+ *   dm id  = "d_" + base32lower(SHA-256(DOMAIN.dm + JCS([a, b] sorted)))[0..26]
+ *   self id= "s_" + base32lower(SHA-256(DOMAIN.self + JCS(person)))[0..26]
+ *
+ * The authority rules over these shapes are `ConvLog.apply`'s (spec §16.7).
+ */
+import { z } from "../../vendor/zod/index.js";
+import { Message, TaskArtifactUpdateEvent, TaskStatusUpdateEvent, Part } from "./a2a.js";
+import { Base64Url, ChannelName, EncKey, Hash, Key32, LIMITS, MachineId, Millis, PersonId, PROTOCOL, SessionName, Ulid } from "./common.js";
+import { DelegationChain, DelegationGrant } from "./delegation.js";
+import { RealmId } from "./realm.js";
+import { ActivationProof } from "./contact-request.js";
+import { GuestInvitation } from "./guest-invitation.js";
+// ---- identifiers (spec §16.1) ----
+/** A person, or one agent of a person (`person/agent`). Every agent belongs to one person. */
+export const ParticipantId = z
+    .string()
+    .regex(/^(?:[a-z][a-z0-9-]{0,31}|p_[a-z2-7]{26})(?:\/[a-z0-9][a-z0-9._-]{0,63})?$/, "person or person/agent");
+/** `d_…` a dm (derived), `s_…` a person's `self` conversation (derived), `c_` + ULID a group or channel. */
+export const ConvId = z.string().regex(/^(?:[ds]_[a-z2-7]{26}|c_[0-7][0-9A-HJKMNP-TV-Z]{25})$/, "conversation id");
+export const ConvKind = z.enum(["dm", "group", "channel", "self"]);
+/** Channels only; every other kind is private. */
+export const Visibility = z.enum(["public", "private"]);
+/** What a late joiner may read: `shared` gets earlier chain keys, `none` reads from its add onwards. */
+export const HistoryPolicy = z.enum(["none", "shared"]);
+export const ConvRole = z.enum(["owner", "admin", "member", "guest"]);
+/** Who may do a thing in a group or channel. */
+export const Permit = z.enum(["all", "admins"]);
+/** Which mentions wake a seated agent: its own person's, any member's (under consent), or none. */
+export const RespondTo = z.enum(["self", "members", "none"]);
+/** A conversation's policy for members' agents mining it as context (spec §16.8). */
+export const AgentContext = z.enum(["members", "seats", "none"]);
+/** Why a sender epoch ends. */
+export const RekeyCause = z.enum(["removed", "device", "added", "settings", "schedule"]);
+const Seq = z.number().int().min(0);
+const RetainDays = z.number().int().min(1).max(LIMITS.retainDaysMax);
+/** A conversation event's signature: 64 bytes. */
+const Sig = z.string().regex(/^[A-Za-z0-9_-]{86}$/, "Ed25519 signature, base64url");
+/** An AES-GCM nonce: 12 bytes. */
+const Nonce = z.string().regex(/^[A-Za-z0-9_-]{16}$/, "12-byte nonce, base64url");
+const isAgent = (p) => p.includes("/");
+// ---- linked channels (spec §16.10; reserved: validated, no daemon behaviour yet) ----
+/** An outside channel a person may link as an alias of themselves. Telegram first, then Slack. */
+export const LinkChannel = z.enum(["telegram", "slack"]);
+/** What a linked channel may do: Jelly's `chat` and `view` action classes (spec §8.11), never more. */
+export const LinkAuthority = z.enum(["chat", "view"]);
+/** Who may mirror a conversation to a linked channel: nobody (the default), its owners and admins, or any member. */
+export const BridgePolicy = z.enum(["none", "admins", "members"]);
+/** The kinds of a `self` conversation's `setting` op: the person's settings, which never expire (spec §16.3). */
+export const SettingKind = z.enum(["prefs", "grant", "context", "localRetention", "link"]);
+/** A sealed op content: base64url(nonce ‖ AES-256-GCM ciphertext ‖ tag), at most a share's size. */
+const SealedState = Base64Url.min(38).max(Math.ceil(((LIMITS.convPlaintextBytes + 28) * 4) / 3));
+// ---- ops (spec §16.2, "Ops") ----
+/** A participant record as an op states it. `device` and `respondTo` are for agent participants only. */
+export const Seat = z
+    .strictObject({ p: ParticipantId, role: ConvRole, device: MachineId.optional(), respondTo: RespondTo.optional() })
+    .refine((s) => isAgent(s.p) || (s.device === undefined && s.respondTo === undefined), { message: "device and respondTo are for agents only" });
+export const ConvOp = z.discriminatedUnion("op", [
+    z.strictObject({
+        op: z.literal("create"),
+        kind: ConvKind,
+        visibility: Visibility.optional(),
+        history: HistoryPolicy,
+        retainDays: RetainDays,
+        /** A channel: the org it is open to when public. */
+        org: z.string().min(1).max(128).optional(),
+        participants: z.array(Seat).min(1).max(LIMITS.convParticipants),
+        /** Absent: `all`. */
+        post: Permit.optional(),
+        invite: Permit.optional(),
+        pins: Permit.optional(),
+        /** JCS(`ConvMeta`) sealed under the creator's epoch-0 message key 0 (spec §16.5). */
+        sealedMeta: Base64Url.max(2048).optional(),
+        /** External human DM: no content or shares until the permanent activation proof. */
+        admission: z.literal("request").optional(),
+    }),
+    z.strictObject({ op: z.literal("add"), participants: z.array(Seat).min(1).max(LIMITS.convOpParticipants) }),
+    z.strictObject({ op: z.literal("accept"), invitation: GuestInvitation.optional() }),
+    z.strictObject({ op: z.literal("activate"), proof: ActivationProof }),
+    z.strictObject({ op: z.literal("request.complete"), request: Ulid, seq: z.number().int().min(2), digest: Hash }),
+    z.strictObject({ op: z.literal("join") }),
+    z.strictObject({ op: z.literal("leave") }),
+    z.strictObject({ op: z.literal("remove"), participants: z.array(ParticipantId).min(1).max(LIMITS.convOpParticipants) }),
+    z.strictObject({ op: z.literal("role"), p: ParticipantId, role: ConvRole }),
+    z.strictObject({ op: z.literal("seat"), p: ParticipantId, device: MachineId.optional(), respondTo: RespondTo.optional() }),
+    z.strictObject({
+        op: z.literal("settings"),
+        visibility: Visibility.optional(),
+        history: HistoryPolicy.optional(),
+        retainDays: RetainDays.optional(),
+        post: Permit.optional(),
+        invite: Permit.optional(),
+        pins: Permit.optional(),
+    }),
+    z.strictObject({ op: z.literal("archive"), on: z.boolean() }),
+    z.strictObject({ op: z.literal("rekey"), epoch: z.number().int().min(1), cause: RekeyCause, device: MachineId.optional(), until: Seq.optional() })
+        .refine((op) => op.cause === "device" ? op.device !== undefined : op.device === undefined && op.until === undefined, { message: "only a device rekey names a device and optional cutoff" }),
+    /**
+     * The agent-context policy and the linked-channel `bridges` policy (spec §16.8, §16.10), in plaintext: an op, so it
+     * never expires, and a joiner who holds no earlier keys still knows it. In a dm or a group, the author's vote.
+     */
+    z
+        .strictObject({ op: z.literal("policy"), agentContext: AgentContext.optional(), bridges: BridgePolicy.optional() })
+        .refine((p) => p.agentContext !== undefined || p.bridges !== undefined, { message: "a policy sets agentContext, bridges or both" }),
+    /** A group's or channel's name, topic and purpose: JCS(`ConvMeta`) sealed under the author's key (`epoch`, `idx`). */
+    z.strictObject({ op: z.literal("meta"), epoch: Seq, idx: Seq, sealed: SealedState }),
+    /** A setting of the person's `self` conversation: JCS(`SettingBody` of `kind`) sealed under (`epoch`, `idx`). */
+    z.strictObject({ op: z.literal("setting"), kind: SettingKind, epoch: Seq, idx: Seq, sealed: SealedState }),
+]);
+/** The plaintext of `create.sealedMeta` and of a `meta` body's fields. */
+export const ConvMeta = z.strictObject({
+    name: ChannelName.optional(),
+    topic: z.string().max(250).optional(),
+    purpose: z.string().max(250).optional(),
+});
+// ---- message bodies (spec §16.3) ----
+export const Mention = z.union([
+    z.strictObject({ p: ParticipantId }),
+    /** Every participant person. Never wakes an agent. */
+    z.strictObject({ all: z.literal("channel") }),
+    /** Every participant person online now. Never wakes an agent. */
+    z.strictObject({ all: z.literal("here") }),
+]);
+/** A file in the relay's blob store, sealed under its own AES-256-GCM key. The shape only; files land later. */
+export const Attachment = z.strictObject({
+    blob: z.string().regex(/^b_[A-Za-z0-9_-]{43}$/, "blob id"),
+    key: Key32,
+    nonce: Nonce,
+    sha256: Hash,
+    bytes: z.number().int().positive().max(LIMITS.blobBytes),
+    mime: z.string().max(100),
+    name: z.string().max(255),
+    thumb: Base64Url.max(16_384).optional(),
+});
+/** A line's provenance when its person wrote it from a linked channel. Signed and sealed with the event. */
+export const Via = z.strictObject({ channel: LinkChannel });
+/**
+ * A person's linked channel, as a human-tier device records it in the person's `self` conversation (never the
+ * device log, which is public). `account` is the channel's own id for the person's account (Telegram `from.id`;
+ * Slack `team/user`); it exists only inside the sealed `self` conversation. The proof is the one-time code's digest
+ * and the six-digit code the person saw match on both sides. `revokedAt` ends it; the last writer wins by `seq`.
+ */
+export const LinkRecord = z.strictObject({
+    id: Ulid,
+    channel: LinkChannel,
+    account: z.string().regex(/^[A-Za-z0-9._:/-]{1,128}$/, "channel account id"),
+    /** The person's device that runs the bridge and wrote this record. */
+    host: MachineId,
+    proof: z.strictObject({ method: z.literal("code-sas"), codeDigest: Hash, sas: z.string().regex(/^[0-9]{6}$/, "six digits") }),
+    authority: z
+        .array(LinkAuthority)
+        .min(1)
+        .max(2)
+        .refine((a) => new Set(a).size === a.length, { message: "each authority once" }),
+    linkedAt: Millis,
+    revokedAt: Millis.optional(),
+});
+/**
+ * Who can read a piece of content, for the audience guard: a person, or a linked channel's provider as
+ * `ext:<channel>:<link id>`. Not on the wire; the guard's reader sets are typed with it.
+ */
+export const ReaderId = z.union([PersonId, z.string().regex(/^ext:(?:telegram|slack):[0-7][0-9A-HJKMNP-TV-Z]{25}$/, "ext:<channel>:<link id>")]);
+export const ReaderSet = z.array(ReaderId).max(LIMITS.convParticipants + LIMITS.convParticipants);
+export const ReceiptStage = z.enum(["delivered", "handed_to_agent", "read"]);
+/**
+ * A task as a thread (spec §16.3): `request` is the thread root, from the requester to an agent participant;
+ * `status` and `artifact` come from that agent; `cancel` and `followUp` from the requester.
+ */
+export const TaskEventBody = z.discriminatedUnion("k", [
+    z.strictObject({ k: z.literal("request"), to: ParticipantId.refine(isAgent, "a task goes to an agent"), message: Message, delegation: DelegationChain }),
+    z.strictObject({ k: z.literal("status"), root: Ulid, update: TaskStatusUpdateEvent }),
+    z.strictObject({ k: z.literal("artifact"), root: Ulid, update: TaskArtifactUpdateEvent }),
+    z.strictObject({ k: z.literal("cancel"), root: Ulid, reason: z.string().max(1000).optional() }),
+    z.strictObject({ k: z.literal("followUp"), root: Ulid, message: Message }),
+]);
+export const ContextAccess = z.enum(["allow", "ask", "off"]);
+export const ContextKind = z.enum(["own", "dm", "group", "channel.private", "channel.public"]);
+export const ContextScope = z.union([z.strictObject({ cid: ConvId }), z.strictObject({ kind: ContextKind })]);
+/** One of a person's rules for which of their agents may mine which conversations (spec §16.8). */
+export const ContextRule = z.strictObject({
+    agent: z.union([SessionName, z.literal("*")]),
+    scope: ContextScope,
+    access: ContextAccess,
+    /** Absent: the conversation's retention. */
+    lookbackDays: RetainDays.optional(),
+});
+const scopeKey = (r) => `${r.agent} ${"cid" in r.scope ? `cid:${r.scope.cid}` : `kind:${r.scope.kind}`}`;
+/** A person's whole rule set: at most one rule per (agent, scope). */
+export const ContextRules = z
+    .array(ContextRule)
+    .max(LIMITS.contextRules)
+    .refine((rules) => new Set(rules.map(scopeKey)).size === rules.length, { message: "at most one rule per agent and scope" });
+/** One sender chain at one index: `ck` is the chain key for message `idx` of `device`'s chain in `epoch`. */
+export const KeyShare = z.strictObject({ epoch: Seq, device: MachineId, idx: Seq, ck: Key32 });
+/** The plaintext of one recipient's sealed share in a `keys` event. */
+export const KeySharePayload = z.strictObject({ shares: z.array(KeyShare).min(1).max(LIMITS.keyShares) });
+/**
+ * The `self` conversation's passing state (spec §16.3, "The self conversation"), in `sync` message bodies: it expires
+ * with the conversation's retention. The last writer wins by `seq`.
+ */
+export const SyncBody = z.discriminatedUnion("s", [
+    z.strictObject({ s: z.literal("read"), cid: ConvId, upTo: Seq, thread: Ulid.optional() }),
+    z.strictObject({ s: z.literal("unread"), cid: ConvId, from: z.number().int().min(1) }),
+    z.strictObject({ s: z.literal("follow"), cid: ConvId, thread: Ulid, on: z.boolean() }),
+    z.strictObject({ s: z.literal("save"), cid: ConvId, target: Ulid, on: z.boolean() }),
+    z.strictObject({ s: z.literal("draft"), cid: ConvId, thread: Ulid.optional(), text: z.string().max(8000) }),
+    z.strictObject({ s: z.literal("joined"), cid: ConvId, on: z.boolean() }),
+    z.strictObject({ s: z.literal("keys"), cid: ConvId, shares: z.array(KeyShare).min(1).max(LIMITS.keyShares) }),
+]);
+/**
+ * The person's settings, each sealed in a `setting` op of their `self` conversation (spec §16.3): ops never expire,
+ * so a setting outlives the retention. `s` is the op's `kind`. The last writer wins by `seq`.
+ */
+export const SettingBody = z.discriminatedUnion("s", [
+    z.strictObject({
+        s: z.literal("prefs"),
+        cid: ConvId,
+        notify: z.enum(["all", "mentions", "none"]),
+        muteUntil: Millis.optional(),
+        /** dms only; absent is off. */
+        receipts: z.boolean().optional(),
+    }),
+    /** A consent grant (spec §6.9), verified with `verifyConsentGrant` over this raw value. */
+    z.strictObject({ s: z.literal("grant"), grant: z.record(z.string(), z.unknown()) }),
+    z.strictObject({ s: z.literal("context"), rules: ContextRules }),
+    z.strictObject({ s: z.literal("localRetention"), cid: ConvId, days: RetainDays }),
+    z.strictObject({ s: z.literal("link"), link: LinkRecord }),
+]);
+/** The plaintext of a `msg` event. */
+export const MsgBody = z.discriminatedUnion("t", [
+    z.strictObject({
+        t: z.literal("line"),
+        text: z.string().max(LIMITS.lineChars),
+        format: z.enum(["plain", "md"]),
+        /** The thread root's event id. */
+        thread: Ulid.optional(),
+        /** A thread reply also shown in the main view. */
+        broadcast: z.boolean().optional(),
+        mentions: z.array(Mention).max(LIMITS.mentions).optional(),
+        files: z.array(Attachment).max(LIMITS.files).optional(),
+        /** A2A data parts, rendered as cards. */
+        parts: z.array(Part).max(8).optional(),
+        /** The mention this line answers. */
+        answers: Ulid.optional(),
+        grants: z.array(DelegationGrant).max(LIMITS.agentMentions).optional(),
+        /** Written by its person from a linked channel. Never on an agent's line. */
+        via: Via.optional(),
+    }),
+    z.strictObject({ t: z.literal("edit"), target: Ulid, text: z.string().max(LIMITS.lineChars), mentions: z.array(Mention).max(LIMITS.mentions).optional() }),
+    z.strictObject({ t: z.literal("delete"), target: Ulid }),
+    z.strictObject({ t: z.literal("react"), target: Ulid, key: z.string().min(1).max(64), on: z.boolean() }),
+    z.strictObject({ t: z.literal("pin"), target: Ulid, on: z.boolean() }),
+    z.strictObject({ t: z.literal("task"), task: TaskEventBody }),
+    z.strictObject({ t: z.literal("receipt"), target: Ulid, stage: ReceiptStage }),
+    z.strictObject({ t: z.literal("sync"), sync: SyncBody }),
+]);
+// ---- events and the log (spec §16.2) ----
+const Position = z.strictObject({ seq: Seq, hash: Hash });
+const header = {
+    v: z.literal(PROTOCOL),
+    realm: RealmId,
+    cid: ConvId,
+    /** Chosen by the author; unique in the conversation. */
+    id: Ulid,
+    by: z.strictObject({ person: PersonId, device: MachineId, agent: SessionName.optional() }),
+    ts: Millis,
+    /** The last op the author applied: its seq and h(seq), or {0, h(0)} before any. */
+    opHead: Position,
+    /** The head the author had, for gossip. */
+    seen: z.strictObject({ seq: z.number().int().min(1), hash: Hash }).optional(),
+};
+/** A control op, in plaintext: the relay routes and checks authority by it. */
+export const ConvOpEvent = z.strictObject({ ...header, class: z.literal("op"), body: ConvOp, sig: Sig });
+/** base64url(nonce ‖ AES-256-GCM ciphertext ‖ tag) of JCS(`MsgBody`), sealed under one message key. */
+export const SealedBody = Base64Url.min(38).max(Math.ceil(((LIMITS.convPlaintextBytes + 28) * 4) / 3));
+/** Everything else, sealed under the author device's sender key at (`epoch`, `idx`). */
+export const ConvMsgEvent = z.strictObject({
+    ...header,
+    class: z.literal("msg"),
+    epoch: Seq,
+    idx: Seq,
+    /** Own-person wake hint only: sessions of `by.person` that this event may wake. */
+    wake: z.array(SessionName).min(1).max(LIMITS.wakeHints).optional(),
+    /** The accepted request reservation. Only a sealed request.import can use it. */
+    request: Ulid.optional(),
+    body: SealedBody,
+    sig: Sig,
+});
+/** One recipient device's share, sealed to it under the envelope seal (spec §5, "Sealing"). */
+export const SealedShare = z.strictObject({
+    to: z.strictObject({ person: PersonId, device: MachineId }),
+    epk: EncKey,
+    nonce: Nonce,
+    ct: Base64Url.max(Math.ceil(((LIMITS.keyShares * 160 + 16) * 4) / 3)),
+});
+/** A `keys` event's body: one share, to one recipient device. */
+export const KeysBody = SealedShare;
+/**
+ * A sender-key or history share to one recipient device (spec §16.6). It is signed like every event but is not an
+ * entry of the log: the relay keeps it for its recipient alone and serves it to no one else (`ConvShareEntry`).
+ */
+export const ConvKeysEvent = z.strictObject({ ...header, class: z.literal("keys"), body: KeysBody, sig: Sig });
+/** The events of the log: ops and messages. */
+export const ConvEvent = z.discriminatedUnion("class", [ConvOpEvent, ConvMsgEvent]);
+/** Every signed conversation event: the log's, and key shares. */
+export const ConvAnyEvent = z.discriminatedUnion("class", [ConvOpEvent, ConvMsgEvent, ConvKeysEvent]);
+/** An event as the relay stores and serves it. The relay does not sign it; members verify the chain. */
+export const ConvLogEntry = z.strictObject({ seq: z.number().int().min(1), prev: Hash, event: ConvEvent });
+/**
+ * A `msg` entry whose body the relay pruned after the retention (spec §16.4): its seq, its prev and the digest
+ * SHA-256(JCS(event)), so the chain stays verifiable (`ConvLog.applyExpired`). An op is never served this way.
+ */
+export const ConvExpiredEntry = z.strictObject({ seq: z.number().int().min(2), prev: Hash, digest: Hash });
+/** What `conv.fetch` serves for one seq: the entry, or its digest once expired. */
+export const ConvServedEntry = z.union([ConvLogEntry, ConvExpiredEntry]);
+/** A key share as the relay serves it to its recipient: `n` orders the recipient's shares of one conversation. */
+export const ConvShareEntry = z.strictObject({ n: z.number().int().min(1), event: ConvKeysEvent });
+/** A log position: a seq and h(seq). */
+export const ConvHead = Position;

package/dist/lib/modules/core/schema/envelope.js

@@ -5,11 +5,12 @@
  */
 import { z } from "../../vendor/zod/index.js";
 import { Message, TaskArtifactUpdateEvent, TaskStatusUpdateEvent } from "./a2a.js";
-import { AgentKind, Base64Url, ChannelName, DeliveryTier, MachineId, MachineLabel, Millis, PersonId, PROTOCOL, SessionAddress, SessionName, SessionState, Ulid, LIMITS, } from "./common.js";
+import { AgentKind, Base64Url, DeliveryTier, MachineId, MachineLabel, Millis, PersonId, PROTOCOL, SessionAddress, SessionName, SessionState, Ulid, LIMITS, } from "./common.js";
 import { CardData, CardGetData, GrantSync } from "./consent.js";
 import { DelegationChain } from "./delegation.js";
 import { ErrorCode } from "./errors.js";
 import { Anchor, RealmId } from "./realm.js";
+import { PortableRequest } from "./contact-request.js";
 export const EnvelopeType = z.enum(["message", "task.status", "task.artifact", "task.cancel", "receipt", "presence"]);
 export const SEAL_ALG = "x25519-hkdf-sha256-a256gcm";
 /**
@@ -62,22 +63,6 @@ export const Envelope = z.object({
     sig: Base64Url,
 });
 // ---- Decrypted body payloads, by envelope type ----
-/** A channel's persons: roster person names, or hosted `p_…` ids in a directory realm (spec §6.8). */
-const ChannelPersons = z.array(PersonId).min(1).max(LIMITS.channelPersons);
-/**
- * A channel change or post (spec §6.8), on a `kind: "message"` envelope sealed to a device with no recipient agent.
- * `create`: the full channel record with the person who created it, to every member device and to each later
- * invitee. `invite`: persons added, to the existing members. `leave`: the sender left. `remove`: persons removed by
- * the creator or an admin, to every member device. `post`: a line in the channel. `name` is always the channel's own
- * name. A DM line has no `conv` (spec §5, "Meaning").
- */
-export const ChannelConv = z.discriminatedUnion("op", [
-    z.object({ kind: z.literal("channel"), op: z.literal("create"), id: Ulid, name: ChannelName, persons: ChannelPersons, creator: PersonId }),
-    z.object({ kind: z.literal("channel"), op: z.literal("invite"), id: Ulid, name: ChannelName, persons: ChannelPersons }),
-    z.object({ kind: z.literal("channel"), op: z.literal("leave"), id: Ulid, name: ChannelName }),
-    z.object({ kind: z.literal("channel"), op: z.literal("remove"), id: Ulid, name: ChannelName, persons: ChannelPersons }),
-    z.object({ kind: z.literal("channel"), op: z.literal("post"), id: Ulid, name: ChannelName }),
-]);
 /**
  * Sync between two devices of one person (spec §6.9, "Sync"): `grant` carries grants the person set or re-signed,
  * `snapshot` every current grant, for a device of the person that is new to the sender. The message carries exactly
@@ -88,14 +73,14 @@ export const SelfConv = z.object({ kind: z.literal("self"), what: z.enum(["grant
  * A message request (spec §6.9, "Message requests"), on an envelope of class `request` from a person to a person:
  * its message carries exactly one text part of at most `LIMITS.requestChars`.
  */
-export const RequestConv = z.object({ kind: z.literal("request") });
+export const RequestConv = z.object({ kind: z.literal("request"), proof: PortableRequest.optional() });
 /**
  * A contact card between two persons (spec §6.9, "Contact cards"): `card` carries one data part `{card}`, the signed
  * card; `get` asks for the receiver's card and carries one data part `{get: true}`.
  */
 export const CardConv = z.object({ kind: z.literal("card"), what: z.enum(["card", "get"]) });
 /** The conversation a `message` belongs to when its ends alone do not say (spec §5, "Meaning"). */
-export const Conv = z.discriminatedUnion("kind", [ChannelConv, SelfConv, RequestConv, CardConv]);
+export const Conv = z.discriminatedUnion("kind", [SelfConv, RequestConv, CardConv]);
 /**
  * type "message". `kind: "task"` asks the recipient to run `message` as a new A2A task;
  * the sender assigns `message.taskId` (a ULID) and `message.contextId`.
@@ -109,11 +94,7 @@ export const MessagePayload = z
     wake: z.boolean().optional(),
     /** Required on `kind: "task"`, absent otherwise: the signed chain from the root requester to this hop (spec §6.7). Receivers run `verifyChain`. */
     delegation: DelegationChain.optional(),
-    /**
-     * The conversation, when the ends do not say it (spec §5, "Meaning"): a channel change or post (§6.8).
-     * `message.messageId` is a ULID shared by every copy; `message.contextId`, when set, is the ULID `messageId` of
-     * the thread's first line.
-     */
+    /** Device-addressed consent sync, portable contact request or contact card. */
     conv: Conv.optional(),
 })
     .refine((p) => (p.kind === "task" ? p.message.taskId !== undefined : true), { message: "a task message needs message.taskId" })
@@ -123,6 +104,9 @@ export const MessagePayload = z
 })
     .refine((p) => p.conv?.kind !== "request" || requestMessage(p.message), {
     message: `a message request carries one text part of 1 to ${LIMITS.requestChars} characters, and nothing else`,
+})
+    .refine((p) => p.conv?.kind !== "request" || p.conv.proof === undefined || (p.message.messageId === p.conv.proof.descriptor.id && p.message.parts[0]?.text === p.conv.proof.opening.text), {
+    message: "a portable request's message id and text match its signed opening",
 })
     .refine((p) => p.conv?.kind !== "card" || cardMessage(p.message, p.conv.what), {
     message: "a card message carries one data part, the card or the request for one, and nothing else",

package/dist/lib/modules/core/schema/errors.js

@@ -11,6 +11,7 @@ export const ErrorCode = z.enum([
     "refused", // recipient policy refuses this sender
     "declined", // the recipient's person declined a held request (spec §6.9)
     "request_required", // the recipient's person has not accepted this sender: a message request comes first (spec §6.9)
+    "peer_outdated", // the other person's devices run a Messaging from before conversations: they need to update first
     "rate_limited", // too many envelopes; retry later
     "loop_guard", // agent-to-agent loop guard tripped
     "too_large", // size limit exceeded
@@ -24,10 +25,12 @@ export const ErrorCode = z.enum([
     "guarded_turn", // a guarded peer turn tried to send outside its allowance (client-side; never on the wire)
     "roster_conflict", // roster entry does not extend the current head; resync and retry
     "invite_invalid", // unknown, expired, revoked, used or mismatched invite
-    "no_identity", // daemon has no identity/team yet
+    "no_identity", // daemon has no usable team identity or bound directory device with published keys
     "binding_invalid", // a device binding, log entry or its authority failed verification (hosted realms)
-    "jelly_unavailable", // Jelly ID's key set or key history could not be fetched; never reported as invalid
+    "jelly_unavailable", // Jelly ID unreachable or an unusable response for keys or sign-in; never reported as invalid
     "log_conflict", // a device-log entry does not extend the log's head; resync and retry
+    "conv_conflict", // a conversation event does not extend the log, or its op head is not the current one; 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; re-seal and retry
     "device_limit", // the person already has LIMITS.devicesPerPerson current devices
     "admission_required", // dir.bind without a Jelly-vouched bind of the connecting device
     "admission_invalid", // dir.bind whose Jelly token is not live, or not for this directory's issuer and resource
@@ -42,8 +45,23 @@ export const ErrorCode = z.enum([
     "ticket_invalid", // deployment "jelly": the session ticket did not verify, expired, or names another session or agent
     "daemon_unavailable", // client could not reach the local daemon socket
     "daemon_mismatch", // the daemon on the socket is another version or IPC protocol than the client (spec §8.2)
+    "store_refused", // messagingd refused the home's store and changed nothing; StoreRefusedError.reason says why: pre-reset or newer (spec §8.8)
     "internal", // unexpected failure; details are logged locally, never sent
 ]);
+/**
+ * The exit status of a messagingd or messaging-relay that refuses its store and changes nothing (spec §8.8): `EX_CONFIG`
+ * of sysexits(3), for either reason. messagingd also prints one stderr line,
+ * `messagingd: store_refused: <reason>: <why and the remedy>`. A client matches this status, the code and the
+ * reason, never the wording.
+ */
+export const STORE_REFUSED_EXIT = 78;
+/**
+ * Why a store is refused (spec §8.8):
+ * - `pre-reset`: it records no store generation, or another one. Starting over (moving the home aside) is the remedy.
+ * - `newer`: its `min_reader` is above this reader's schema: a newer messagingd wrote it. Upgrading is the remedy;
+ *   moving the home aside would set a newer home aside.
+ */
+export const StoreRefusedReason = z.enum(["pre-reset", "newer"]);
 export const ErrorBody = z.object({
     code: ErrorCode,
     message: z.string().max(500),
@@ -60,6 +78,28 @@ export class MessagingError extends Error {
         return { code: this.code, message: this.message.slice(0, 500) };
     }
 }
+/** `store_refused`, with its reason as a field: clients branch on `reason`, never on the message. */
+export class StoreRefusedError extends MessagingError {
+    reason;
+    constructor(reason, message, options) {
+        super("store_refused", message, options);
+        this.name = "StoreRefusedError";
+        this.reason = reason;
+    }
+}
+/** The stderr line of a messagingd that refuses its store: `messagingd: store_refused: <reason>: <text>`. */
+export function storeRefusedLine(reason, text) {
+    return `messagingd: store_refused: ${reason}: ${text}`;
+}
+/**
+ * The reason on a messagingd refusal line, or undefined for any other line. Reads the tokens only; the text after
+ * them may change between releases.
+ */
+export function storeRefusedReason(line) {
+    const match = /^messagingd: store_refused: ([a-z-]+): /.exec(line);
+    const parsed = StoreRefusedReason.safeParse(match?.[1]);
+    return parsed.success ? parsed.data : undefined;
+}
 export function isMessagingError(value) {
     return value instanceof MessagingError;
 }

package/dist/lib/modules/core/schema/guest-invitation.js

@@ -0,0 +1,13 @@
+/** A bounded, sealed preview. Its signature is portable; the guest accepts exactly this op head and exposure. */
+import { z } from "../../vendor/zod/index.js";
+import { Hash, LIMITS, MachineId, Millis, PersonId, PROTOCOL, Ulid } from "./common.js";
+import { RealmId } from "./realm.js";
+export const GuestInvitation = z.strictObject({
+    v: z.literal(PROTOCOL), realm: RealmId, cid: z.string().regex(/^c_[0-7][0-9A-HJKMNP-TV-Z]{25}$/),
+    id: Ulid, to: PersonId, inviter: PersonId, by: MachineId,
+    head: z.strictObject({ seq: z.number().int().min(1), hash: Hash }), issuedAt: Millis, expiresAt: Millis,
+    kind: z.enum(["channel", "group"]), history: z.enum(["shared", "none"]),
+    agentContext: z.enum(["members", "seats", "none"]), bridges: z.enum(["members", "admins", "none"]),
+    audience: z.array(z.strictObject({ p: z.string().min(1).max(100), person: PersonId, role: z.enum(["owner", "admin", "member", "guest"]), state: z.enum(["member", "invited"]) })).min(1).max(LIMITS.convParticipants),
+    sig: z.string().regex(/^[A-Za-z0-9_-]{86}$/),
+});

package/dist/lib/modules/core/schema/index.js

@@ -13,3 +13,9 @@ export * from "./directory-frames.js";
 export * from "./ipc.js";
 export * from "./ipc/device.js";
 export * from "./ipc/consent.js";
+export * from "./conversation.js";
+export * from "./conv-frames.js";
+export * from "./contact-request.js";
+export * from "./guest-invitation.js";
+export * from "./ipc/conversation-views.js";
+export * from "./ipc/conversations.js";

package/dist/lib/modules/core/schema/ipc/consent.js

@@ -3,11 +3,12 @@
  * socket refuses them, and agents never set or read a person's grants. Spread into `IPC_METHODS`.
  */
 import { z } from "../../../vendor/zod/index.js";
-import { ChannelName, LIMITS, MachineId, MachineLabel, Millis, PersonId, RoomRef, SessionAddress, SessionName, Ulid } from "../common.js";
+import { LIMITS, MachineId, MachineLabel, Millis, PersonId, SessionAddress, SessionName, Ulid } from "../common.js";
+import { ConvId, ParticipantId } from "../conversation.js";
 import { AgentMailLevel, AskLevel, CardCan, ChatLevel } from "../consent.js";
 import { Email } from "../directory-frames.js";
-/** A grant's subject as a person names it: a person, or a channel by its name here. */
-export const GrantTarget = z.union([z.strictObject({ person: PersonId }), z.strictObject({ channel: ChannelName })]);
+/** A grant's subject: a person, or a verified conversation id. */
+export const GrantTarget = z.union([z.strictObject({ person: PersonId }), z.strictObject({ conv: ConvId })]);
 const Levels = {
     chat: ChatLevel.optional(),
     agentMail: AgentMailLevel.optional(),
@@ -17,7 +18,7 @@ const Levels = {
 };
 /** A grant as this device holds it. A channel subject carries the channel's id and, while this person is in it, its name here. */
 export const GrantView = z.object({
-    subject: z.union([z.object({ person: PersonId }), z.object({ channel: Ulid, name: ChannelName.optional() })]),
+    subject: GrantTarget,
     ...Levels,
     id: Ulid,
     ts: Millis,
@@ -61,13 +62,15 @@ export const AskRequest = z.object({
  * write to them. `name`, `email` and `org` are the realm's verified profile of the sender, never the request's text.
  */
 export const ContactRequestView = z.object({
-    /** The envelope id. */
+    /** The portable request id; old unsigned requests explicitly require a resend. */
     id: Ulid,
     kind: z.literal("contact"),
+    cid: ConvId.optional(),
+    state: z.enum(["pending", "answering", "accepted", "resend"]),
     from: z.object({
         person: PersonId,
         device: MachineId,
-        label: MachineLabel,
+        label: MachineLabel.optional(),
         name: z.string().max(200),
         email: z.string().max(320).optional(),
         org: z.enum(["same", "other", "none"]),
@@ -77,6 +80,7 @@ export const ContactRequestView = z.object({
     at: Millis,
     exp: Millis,
 });
+export const AgentInvitationRequest = z.strictObject({ kind: z.literal("agent-invitation"), id: Ulid, cid: ConvId, from: ParticipantId, to: ParticipantId, at: Millis });
 /**
  * A contact one of this person's agents asks them to make (spec §6.9, "Message requests"): `send {to: "me", request:
  * {contact}}`. Only the person sends a message request, with `contact.request`; answering this one `decline`
@@ -91,7 +95,7 @@ export const ContactSuggestion = z.object({
     at: Millis,
 });
 /** What `request.list` lists: asks to the person's agents, message requests, and contacts their agents suggest. */
-export const HeldRequest = z.union([AskRequest, ContactRequestView, ContactSuggestion]);
+export const HeldRequest = z.union([AskRequest, ContactRequestView, ContactSuggestion, AgentInvitationRequest]);
 /**
  * For an ask: `once` delivers it, guarded; `always` sets the sender's grant to `ask: "open"` (keeping its other
  * levels), then delivers it, guarded. For a message request: `accept` sets the sender's grant to `chat: "open"`
@@ -152,7 +156,7 @@ export const CONSENT_METHODS = {
     "request.answer.preview": {
         params: RequestAnswerParams,
         result: z.object({
-            kind: z.enum(["message", "task", "contact", "suggestion"]),
+            kind: z.enum(["message", "task", "contact", "suggestion", "agent-invitation"]),
             from: z.object({ name: z.string().max(200), email: z.string().max(320).optional(), org: z.enum(["same", "other", "none"]) }),
             agent: SessionName.optional(),
             to: SessionName.optional(),
@@ -169,7 +173,7 @@ export const CONSENT_METHODS = {
      */
     "contact.request": {
         params: ContactRequestParams,
-        result: z.object({ id: Ulid, conversation: RoomRef, person: PersonId }),
+        result: z.object({ id: Ulid, cid: ConvId, person: PersonId }),
     },
     /** Whether `contact.request` would find a person for `email`; counts against the directory's lookup limits. Sends nothing. */
     "contact.request.preview": { params: ContactRequestParams.partial({ text: true }), result: z.object({ found: z.boolean() }) },