# Chatto API Rules

> Design rules concerning Chatto's ConnectRPC API, both resources and realtime

- Skill: `chattocorp/chatto-api-rules` (Agent Skill)
- Install (CLI): `npx skillmds@latest add chattocorp/chatto-api-rules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chattocorp/chatto-api-rules/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: chattocorp (https://skillmd.com/u/chattocorp)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chattocorp/chatto-api-rules

---


### ConnectRPC Resource API

- Define one canonical public protobuf for each resource. Reuse that protobuf
  across list, get, batch, and mutation-response surfaces when the
  authorization and lifecycle semantics are the same.
- Keep services complete for their resource and scope. Add bounded batch reads
  when events or related resources commonly expose IDs that clients must
  hydrate.
- Keep commands, explicit reads, pagination, history, and read-your-writes
  responses in ConnectRPC. Realtime delivery does not replace these APIs.
- Resource `Update*` RPCs must use `google.protobuf.FieldMask update_mask`.
  Unselected fields stay unchanged; selected fields can be set or cleared,
  subject to validation. Apply masks before validation. Omitted masks infer
  populated fields; explicit empty masks are invalid. Clients should send
  explicit paths. Commands use specific verbs such as `Set`, `Change`, or
  `Refresh`.

### Realtime API

- Cover the complete useful product event surface for integrations, bots, and
  clients. Do not limit the public event catalogue to events used by the
  bundled frontend.
- Use `chatto.core.evt.v1.Event` for durable EVT facts and
  `chatto.core.pubsub.v1.PubSubEvent` for transient NATS Core signals. Use the
  dedicated `chatto.realtime.v1.RealtimeEvent` union and domain payload catalog
  for public delivery. Keep a semantic one-to-one relationship for selected
  public events without importing core payload types into the public schema.
  Client-facing `PubSubEvent` variants should reference public payload types
  directly. Keep the restricted private union as the allow-list for cursorless
  delivery.
- Keep transport concerns in `chatto.realtime.v1` wrappers. Handshakes,
  subscriptions, catch-up, cursors, heartbeats, errors, and close
  guidance are not domain events.
- Create a fresh authorized `RealtimeEvent` for each public delivery. The
  public payload schema must omit internal variants and storage-only fields.
  Never send stored bytes or mutate a stored event during mapping.
- Keep current resources in ConnectRPC. Let a resource client bind reads to an
  opaque realtime start cursor, then close the interval with event catch-up.
  Do not attach resource sidecars to normal event frames.
- Keep public cursors opaque, confidential, integrity-protected, and bound to
  their viewer and scope. Do not expose NATS or JetStream coordinates.
- Keep wire volume bounded. Resume must have sequence, event-count, time, and
  concurrency limits. Large and lazy collections stay in paginated ConnectRPC
  APIs.
- Use consistent product terminology and names. Public comments must not
  depend on backend terms such as projections, NATS, or JetStream.
- Use a new behavioral protocol version when a change requires all clients to
  change their behavior. Do not use a capability matrix to restate required
  frame semantics.
- When an `Event` or `PubSubEvent` variant must reach clients, update the
  dedicated payload, public union member, authorization and mapper coverage,
  consuming reducers, generated clients, architecture inventory, public
  documentation, and compatibility notes in the same change. Keep public names
  and compact union numbers independent from the internal event source. Use
  independent public payload field numbers and explicit typed mapping for EVT.
  Reference the public payload directly from client-facing pubsub variants and
  deep-copy it at the delivery boundary.
- Keep protobuf comments, public API overviews, tutorials, compatibility
  guidance, and release notes current.