chat

Overview ¶

Package chat defines the built-in `chat` type — a CRDT-backed stream of messages stored as one record per message on a per-object `chat_messages` dataset. Mirrors the markdown package's shape: a registered handler.Type plus aggregating helpers in api.go.

Wire / storage shape of one message record:

{
  "id":               "<auto-derived from changeId>",
  "_ver": { "id": "<VersionId of creating change>", ... },  // SDK-managed
  "creator":          "<accountId>",                     // server-stamped
  "createdAt":        {"$date": "<RFC 3339>"},           // server-stamped
  "modifiedAt":       {"$date": "<RFC 3339>"},           // bumped on edit
  "replyToMessageId": "<msgId>",                         // optional
  "agent": {                                             // optional, create-only
    "name": "<display label>", "debugLink": "<any://…>", "done": <bool>
  },
  "text":             "<markdown>",                      // ≤ MaxTextBytes
  "mentions":         ["<accountId>", ...],              // server-derived
  "attachments":      {                                  // optional, create-only
    "<id>": { "type": "<link|image|…>", "link": "<url>" }
  },
  "reactions":        { "<emoji>": { "<accountId>": <changeTimestamp> } }
}

`attachments` is a UI-side affordance — a map keyed by short opaque ids (≤ MaxAttachmentIdBytes, [A-Za-z0-9_-]+) carrying {type, link}. Create-only — the handler rejects $set on the attachments path post-create — so once a message lands, its attachments are immutable (matches reactions' append-only stance, simpler to reason about across peers).

`agent` marks the message as authored by an agent acting on the signer's behalf (vs the signer typing it directly). It is NOT cryptographically verified — `creator` is still the change signer; the group is a UI hint, useful e.g. as a "human said this, please respond" trigger for an agent subscribed to agent-less messages. Fields: `name` (required display label), `debugLink` (optional drill-down into the run's debug page, by convention `any://<spaceId>/<objectId>[#turn_<n>]` — opaque to the server) and `done` (required liveness bool: false while the producing run is still going, true on terminal messages; clients key their typing indicator on it). Create-only and immutable as a group, like attachments.

Chronological order is `_ver.id` — the SDK's creation-version marker, set once when the record is created (newRecord) and never updated by subsequent modifies. Same role heart's `_o.id` plays. The chat handler does NOT stamp a parallel order field; sort by `_ver.id` and pagination cursors translate to message-id → _ver.id lookups at the API layer.

Reactions are stored emoji-keyed at the first segment, identity- keyed at the second: `reactions.<emoji>.<accountId> = <ts>`. The timestamp is the triggering change's clock, server-derived (the client's payload value is overwritten via sink.Derive). Two invariants follow:

• Authorization on react ops is a single path-segment compare: path[2] (the accountId leaf) must equal ctx.Change.Creator. Anyone can toggle their own slot; nobody can toggle someone else's.
• The emoji and accountId are both first-class storage keys, so a single CRDT $set/$unset on the leaf path adds or removes one identity's reaction with one emoji — no array shuffling.

Reads return the storage shape verbatim: `{emoji: {accountId: ts}}`.

`mentions` is server-DERIVED, never client-supplied (spoofable both ways otherwise: silent-ping griefing and notification suppression — the text is the source of truth). At change materialization the handler parses the message text for mention links (`any://m/<spaceId>/<identity>`, anyuri.ExtractMentions) and stamps the deduped identity array; when the message is a reply (`replyToMessageId`), the replied-to message's creator is folded in — a reply IS a ping to the original author, and folding it in at write time keeps every consumer (badge counter, push, "mentions of me" query) a single indexed field check. Edits re-derive the array from the new text (the reply fold-in re-reads via ctx.Get; the replied-to creator is immutable so this is replica-deterministic). Absent when the message mentions nobody — the sparse idx_mentions index stays proportional to mentioning messages. v1 does not distinguish reply-derived entries from text mentions: a ping is a ping. Self-mentions are not filtered — the array is an objective fact of the message; "not my own messages" is a client-side creator != me filter (and read-tracking never badges self-authored changes anyway).

Server-stamped fields land via sink.Derive in BeforeCreate / BeforeModify; they are intentionally invisible to client payloads. The handler rejects payloads that try to set them directly.